home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / xco212p.zip / DOC / xdsug.inf (.txt) < prev   
OS/2 Help File  |  1996-03-05  |  233KB  |  8,948 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Disclaimer ΓòÉΓòÉΓòÉ
  3.  
  4. This on-line document was generated automatically from its printed version 
  5. LaTeX source. Some places in the document (especially tables) may look ugly due 
  6. to the conversion program limits. These problems are being worked on and are 
  7. supposed to be solved in the final release. 
  8.  
  9.  
  10. ΓòÉΓòÉΓòÉ 2. Title Page ΓòÉΓòÉΓòÉ
  11.  
  12. [11pt,makeidx,a4]book 
  13.  
  14.  xTech Development System 
  15.  
  16.  Native XDS v2.12 
  17.  for 
  18.  IBM Operating System/2 
  19.  
  20.  User's Guide 
  21.  
  22.  xTech Ltd, 1995 
  23.  
  24. empty page0 
  25.  
  26. XDS software and documentation copyright  1991-1995 xTech Ltd. (xTech). 
  27.  
  28. Information in this document is subject to change without notice and does not 
  29. represent a commitment on the part of xTech. 
  30.  
  31. All rights reserved. You may use the enclosed software on a single computer; 
  32. transfer the software from one computer to another, provided that the software 
  33. is used on only one computer at a time and that you remove any copies of the 
  34. software on the computer from which the copies were made; make copies of the 
  35. software for backup purposes only. 
  36.  
  37. XDS software and documentation have been tested and reviewed. Nevertheless, 
  38. xTech makes no warranty or representation, either express or implied, with 
  39. respect to the software and documentation included with XDS. In no event will 
  40. xTech be liable for direct, indirect, special, incidental or consequential 
  41. damages resulting from any defect in the software or documentation included 
  42. with this product. In particular, xTech shall have no liability for any 
  43. programs or data used with this product, including the cost of recovering 
  44. programs or data. 
  45.  
  46. XDS is trademark of xTech Ltd. 
  47.  
  48. IBM, Operating System/2, OS/2, Presentation Manager, C Set/2 are trademarks of 
  49. IBM Corporation. All trademarks and copyrights mentioned in this documentation 
  50. are the property of their respective owners. 
  51.  
  52.  
  53. ΓòÉΓòÉΓòÉ 3. About XDS ΓòÉΓòÉΓòÉ
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 3.1. Welcome to XDS ΓòÉΓòÉΓòÉ
  57.  
  58. xTech development system (XDSTM) is a professional system available for most 
  59. popular platforms, including IBM PC (PC/MS-DOS, Windows 95, Windows NT, OS/2, 
  60. Linux and other Unices), Unix workstations (Sun, HP, DEC, MIPS, etc), 
  61. Macintosh, Amiga, etc. XDS provides a uniform programming environment for all 
  62. mentioned platforms and allows to design and implement truly portable software. 
  63.  
  64. The system contains both Modula-2 and Oberon-2 compilers. These languages are 
  65. often called ``safe'' and ``modular''. The principle innovation of the language 
  66. Modula-2 was the module concept, information hiding and separate compilation. 
  67.  
  68. Oberon-2 is an object-oriented programming (OOP) language based on Modula-2. 
  69. With the introduction of object-oriented facilities, extensible project design 
  70. became much easier. Meanwhile Oberon-2 is quite simple and easy to learn and 
  71. use, unlike other OOP languages such as C++ or Smalltalk. 
  72.  
  73. The XDS Modula-2 compiler implements ISO standard of Modula-2. The ISO standard 
  74. library set is accessible for both Modula-2 and Oberon-2. 
  75.  
  76. XDS is based on a platform-independent front-end for both source languages 
  77. which performs all syntactic and semantic checks on the source program. The 
  78. compiler builds an internal representation of the compilation unit in a memory 
  79. and performs platform-independent analysis and optimizations. After that the 
  80. compiler emits output code. It can be either a native code for the target 
  81. platform or a text in the ANSI C language. The ANSI C code generation is 
  82. available for all platforms. A number of platforms for which a native code 
  83. compiler is available is constantly extended. 
  84.  
  85. Moving to a new language usually means throwing away or rewriting your existing 
  86. library set which could have been the work of many years. XDS allows the 
  87. programmer to mix Modula-2, Oberon-2, C, Assembler, and often Pascal and 
  88. Fortran modules and libraries in a single project. 
  89.  
  90. XDS includes standard ISO and PIM libraries along with a set of utility 
  91. libraries and an interface to the ANSI C library set. 
  92.  
  93. XDS compilers for OS/2 produce highly optimized 32-bit code and debug 
  94. information in the Codeview format. The complete OS/2 32-bit API (including 
  95. Presentation Manager) support is provided for both Modula-2 and Oberon-2 
  96. programs. 
  97.  
  98.  
  99. ΓòÉΓòÉΓòÉ 3.2. Conventions used in this manual ΓòÉΓòÉΓòÉ
  100.  
  101.  
  102. ΓòÉΓòÉΓòÉ 3.2.1. Language descriptions ΓòÉΓòÉΓòÉ
  103.  
  104. Where formal descriptions for language syntax constructions appear, an extended 
  105. Backus-Naur Formalism (EBNF) is used. 
  106.  
  107. These descriptions are set in Courier font. 
  108.  
  109. Text= Text [{Text}] | Text.
  110.  
  111. In EBNF, Brackets [ and ] denote optionality of the enclosed expression, braces 
  112. { and } denote repetition (possibly 0 times), and the line | denotes other 
  113. possible valid descriptions. 
  114.  
  115. Non-terminal symbols start with an upper case letter (e.g. Statement). Terminal 
  116. symbols either start with a lower case letter (e.g. ident), or are written in 
  117. all upper case letters (e.g. BEGIN), or are enclosed within quotation marks 
  118. (e.g. ":="). 
  119.  
  120.  
  121. ΓòÉΓòÉΓòÉ 3.2.2. Source code fragments ΓòÉΓòÉΓòÉ
  122.  
  123. When fragments of a source code are used for examples or appear within a text 
  124. they are set in a Courier font. 
  125.  
  126. MODULE Example;
  127.  
  128. IMPORT InOut;
  129.  
  130. BEGIN
  131.   InOut.WriteString("This is an example");
  132.   InOut.WriteLn;
  133. END Example.
  134.  
  135.  
  136. ΓòÉΓòÉΓòÉ 4. Configuring XDS ΓòÉΓòÉΓòÉ
  137.  
  138.  
  139. ΓòÉΓòÉΓòÉ 4.1. System search paths ΓòÉΓòÉΓòÉ
  140.  
  141. In order that your operating system should know where to find the executable 
  142. binary files which constitute the XDS package, you must set your operating 
  143. system search paths appropriately. See your on-line documentation. 
  144.  
  145.  
  146. ΓòÉΓòÉΓòÉ 4.2. Working configuration ΓòÉΓòÉΓòÉ
  147.  
  148. The working configuration of XDS includes an utility (xc), that combines 
  149. Modula-2 and Oberon-2 compilers, and a set of the system files A name of a 
  150. system file is constructed from the name of the main utility and standard 
  151. filename extension. If you rename the xc utility, you should also rename all 
  152. system files.: 
  153.  
  154. The appearance of the following table is a known problem and will be improved 
  155. in the final release. 
  156.  
  157. ll xc.red| Search path redirection file (See Redirection file) 
  158.  xc.cfg| Configuration file (See Configuration file) 
  159.  xc.msg| Contains texts of error messages (See Customize XDS messages) 
  160.  
  161. When invoked the xc tries to locate the xc.red file in the current directory or 
  162. in the directory where XDS is placed. 
  163.  
  164. Other system files are sought by paths defined by xc.red. If xc.red is not 
  165. found, or it does not contain paths for a system file, the system file is 
  166. sought in the current directory or in the directory where XDS is placed. 
  167.  
  168. The configuration file contains setting that are relevant for all projects. A 
  169. project specific settings are defined in a project file (See Project files). A 
  170. so-called template file is used to simplify the process of building program 
  171. (See Template files). 
  172.  
  173. The configuration and redirection file, project and template files define a 
  174. working environment for a XDS user. The common features of all these files are 
  175. described in More about XDS environment. 
  176.  
  177. The portable software development is one the main goal of XDS. To achieve the 
  178. goal not only source text should be portable between various platforms, but the 
  179. environment also. The XDS introduces a portable notation for file names that 
  180. may be used in all system files and on the command line. The portable notation 
  181. combines MS-DOS and Unix notations (file names are case sensitive): 
  182.  
  183.         [drive letter:] unix file name
  184.  
  185. Examples 
  186.  
  187.         c:/xds/bin
  188.         /mnt/users/alex/cur_pro
  189.         cur_pro/sources
  190.  
  191. Along with the base directory macro (See More about XDS environment) this 
  192. portable notation allows to write all environment files in a platform 
  193. independent and position independent manner. 
  194.  
  195.  
  196. ΓòÉΓòÉΓòÉ 4.3. XDS memory usage ΓòÉΓòÉΓòÉ
  197.  
  198. The XDS compilers are written itself in Oberon-2We use XDS for all our 
  199. developments.. As any other Oberon programs the compilers use garbage collector 
  200. to deallocate memory. Most operating systems (such as OS/2, Windows NT and 
  201. Windows 95) provide virtual memory which can be significantly larger than the 
  202. physical memory. If the amount of memory used by an Oberon-2 program is larger 
  203. than the amount of physical memory, the garbage collector is inefficient. Thus, 
  204. it is important to restrict the amount of memory that can be used by an 
  205. Oberon-2 program. As a rule, such restrictions are set in the configuration or 
  206. project file (See HEAPLIMIT and GCTHRESHOLD equations). 
  207.  
  208. For the compilers itself, two equations (COMPILERHEAP and COMPILERTHRES) should 
  209. be used to control the amount of memory to use. These equations are set in the 
  210. configuration file (xc.cfg). We recommend to set these equations just now 
  211. according to the amount of the physical memory in your computer: 
  212.  
  213. The appearance of the following table is a known problem and will be improved 
  214. in the final release. 
  215.  
  216. c|c|c RAM in megabytes | COMPILERHEAP | COMPILERTHRES 
  217.  2-8 | 4000000 | 2000000 
  218.  8-16 | 6000000 | 3000000 
  219.  16-? | 8000000 | 4000000 
  220.  
  221. It may be necessary to increase COMPILERHEAP if you get the out of memory 
  222. message. It is very unlikely, if the COMPILERHEAP is set to 8 megabytes. Your 
  223. compilation unit should be very large to exceed this memory limit. 
  224.  
  225. Vice versa, if you see unusually intensive disk activity when compiling your 
  226. program it may indicate that the value of the COMPILERHEAP equation is too 
  227. large for your system configuration. 
  228.  
  229.  
  230. ΓòÉΓòÉΓòÉ 4.4. Directory hierarchies ΓòÉΓòÉΓòÉ
  231.  
  232. XDS gives you complete freedom over where you keep both your source code files 
  233. and any files which XDS itself creates for further use. It is advisable to work 
  234. in a project oriented fashion - i.e. have a separate directory hierarchy for 
  235. each individual project. 
  236.  
  237. Due to the re-usable nature of modules written in Modula-2 or Oberon-2, it is 
  238. wise to keep a separate directory for those files which are to be made 
  239. available to all projects. We will call such files the library files. 
  240.  
  241. We recommend you to have a separate working directory for each project. For 
  242. example, to create a directory structure for a project called myproj: 
  243.  
  244. mkdir myproj
  245.  
  246. Set your current working directory to this new directory 
  247.  
  248. cd myproj
  249.  
  250. You will always need subdirectories to store the symbol files and generated 
  251. code files. We recommend to use the script xdsuser or customized version of it 
  252. to create all subdirectories and system files (e.g. xc.red). 
  253.  
  254.  
  255. ΓòÉΓòÉΓòÉ 4.5. XDS search paths ΓòÉΓòÉΓòÉ
  256.  
  257. Upon activation, XDS looks for a file called xc.red - the redirection file. 
  258. This file defines the paths by which all other files are located. If the 
  259. redirection file is not found in the current directory it is sought in the 
  260. directory where XDS executable is placed. 
  261.  
  262.  
  263. ΓòÉΓòÉΓòÉ 4.5.1. Redirection file ΓòÉΓòÉΓòÉ
  264.  
  265. A redirection file consists of several lines of the formSee also More about XDS 
  266. environment: 
  267.  
  268.    pattern = directory {";" directory}
  269.  
  270. It is possible to put comment lines into the redirection file. A comment line 
  271. should start from "%" symbol. A pattern is a regular expression which all 
  272. filenames used by XDS will be compared with. A pattern may contain the wildcard 
  273. symbols '*' and '?', where 
  274.  
  275.  *         stands for any (possibly empty) string, 
  276.  
  277.  ?         stands for any single character. 
  278.  
  279.  For a full description of extended use of wildcards see Regular expression. 
  280.  
  281.  A portable notation is used for directory names or paths (See Working 
  282.  configuration). A path may be absolute or relative, i.e. may consist of full 
  283.  names such as 
  284.  
  285.   /usr/myproj/def
  286.  
  287.  or of names relative to the current directory, such as 
  288.  
  289.   def
  290.  
  291.  denoting the directory def which is a subdirectory of the current working 
  292.  directory. A single dot as a pathname represents the current working 
  293.  directory, a double dot represents the parent, i.e. the directory which has 
  294.  the current working directory as a subdirectory. 
  295.  
  296.  The base directory macro $!can be used in a directory name. It denotes the 
  297.  path to the redirection file. If the redirection file is placed in the 
  298.  /usr/alex directory then $!/sym denotes /usr/alex/sym, while $!/.. denotes 
  299.  /usr directory. 
  300.  
  301.  For any file, its name is sequentially compared with the patterns of each 
  302.  line. If a match is found, then the file is sought for in the first of the 
  303.  directories listed on that line, then in the second directory and so on until 
  304.  either the file is found, or there are no more directories to search or there 
  305.  are no more patterns to match. 
  306.  
  307.  If XDS cannot find a file which is needed for correct execution, e.g. a 
  308.  necessary symbol file, then it will terminate with an appropriate error 
  309.  message. 
  310.  
  311.  When creating a file XDS also uses redirection, and its behavior is determined 
  312.  by the OVERWRITE option. If the option is set and a file is found, then any 
  313.  updates to this file will be re-written to the directory in which it was 
  314.  found. 
  315.  
  316.  If no file of the same name as the one which XDS needs to create is found or 
  317.  the OVERWRITE option is set off, then the file will be created in the 
  318.  directory which appears first in the search path list appropriate to the 
  319.  filename pattern. 
  320.  
  321.  If no pattern matching a given filename can be found in the xc.red file, then 
  322.  the file will be read from (or written to) the current working directory. 
  323.  
  324.  Note: If a pattern matching a given filename is found then XDS will never look 
  325.  into the current directory, unless it is explicitly specified in the search 
  326.  path. 
  327.  
  328.  The following entry in xc.red would be appropriate for searching for the 
  329.  symbol files (provided a symbol file has a .sym extension. 
  330.  
  331.   *.sym=sym;/usr/xds/lib/sym;.
  332.  
  333.  Using the above redirection file the compiler will first search for symbol 
  334.  files in the directory sym which is a subdirectory of the current working 
  335.  directory; then in the directory storing the XDS library symbol files and then 
  336.  in the current directory. 
  337.  Example of the redirection file: 
  338.  
  339.   xc.msg = /xds/bin
  340.   *.mod = mod
  341.   *.def = def
  342.   *.ob2 = oberon
  343.   *.sym = sym; /xds/sym
  344.   *.obj = obj
  345.  
  346.  
  347. ΓòÉΓòÉΓòÉ 4.5.2. Regular expression ΓòÉΓòÉΓòÉ
  348.  
  349. A regular expression is a string containing certain special symbols. These are 
  350.  
  351.  *         denotes an arbitrary sequence of any characters, possibly empty 
  352.            (equivalent to {\000-\377} expression) 
  353.  
  354.  ?         denotes an arbitrary single character; (equivalent to [\000-\377] 
  355.            expression) 
  356.  
  357.  [characters] denotes one of the listed characters 
  358.  
  359.  {characters} denotes an arbitrary sequence of the listed characters; 
  360.  
  361.  \nnn      denotes the ASCII character with octal code nnn where n is [0-7]. 
  362.  
  363.  &         denotes the logical operation AND; 
  364.  
  365.  |         denotes the logical operation OR; 
  366.  
  367.  '136      denotes the logical operation NOT; 
  368.  
  369.  (..)      sets the priority of operations; 
  370.  
  371.  A sequence of the form a-b used within either [] or {} brackets denotes all 
  372.  ASCII characters from a to b. 
  373.  Examples 
  374.  
  375.  *.def 
  376.  
  377.            all files whose extension is .def 
  378.  
  379.  project.* 
  380.  
  381.            files whose name is project with an arbitrary extension 
  382.  
  383.  *.def|*.mod 
  384.  
  385.            files whose extension is either .def or .mod 
  386.  
  387.  \{a-z\}*X.def 
  388.  
  389.            files starting with any sequence of letters, ending in one final "X" 
  390.            and having the extension .def. 
  391.  
  392.  
  393. ΓòÉΓòÉΓòÉ 4.6. Options ΓòÉΓòÉΓòÉ
  394.  
  395. A rich set of XDS options allows one to control the source language, code 
  396. generation and internal limits and settings. We distinguish between boolean 
  397. options (or just options) and equations. An option can be set ON (TRUE) or OFF 
  398. (FALSE), while an equation value is a string. In this chapter we describe only 
  399. the syntax of setup directive. The full list of XDS options and equations is 
  400. provided in the Chapter Compiler Options and Equations. 
  401.  
  402. Options and equations may be set in the configuration file (See Configuration 
  403. file), on the command line (See ???) and in the project file (See Project 
  404. files). Options may also be set in the source text (See Source code 
  405. directives). 
  406.  
  407. The same syntax of a setup directive is used in the configuration and project 
  408. file and on the command line. The only difference is that arbitrary spaces are 
  409. permitted in files, but not on the command line. Option and equation names are 
  410. case independent. 
  411.  
  412. SetupDirective   = DeclareOption
  413.                  | DeclareSynonym
  414.                  | SetOption
  415.                  | DeclareEquation
  416.                  | SetEquation
  417. DeclareOption    = '-' name ':' [ '+' | '-' ]
  418. DeclareSynonym   = '-' name ':=' name
  419. SetOption        = '-' name '+'| '-' name '-'
  420. DeclareEquation  = '-' name '!' [ value ]
  421. SetEquation      = '-' name '=' [ value ]
  422.  
  423. All options and equations used by XDS are predeclared. 
  424.  
  425. The DeclareSynonym directive allows one to use a desirable name (e.g. shorter 
  426. name) for some option. 
  427. Examples 
  428.  
  429. The appearance of the following table is a known problem and will be improved 
  430. in the final release. 
  431.  
  432. l|p8.0cm Directive | Meaning 
  433.  -m2extensions | M2EXTENSION is set OFF 
  434.  -M2Extensions+ | M2EXTENSION is set ON 
  435.  -debug: | DEBUG is declared and set OFF 
  436.  -DemoVersion:+ | DEMOVERSION is declared and set ON 
  437.  -T:=CheckIndex | the T is declared as synonym to CHECKINDEX 
  438.  -Vers!1.0 | VERS is declared and set to "1.0" 
  439.  -Oberon=o2 | OBERON is set to "o2" 
  440.  
  441. Note: The syntax of the setup directive described above was introduced in XDS 
  442. v2.04. The new syntax is more portable, e.g. it can be used in the MacOS/MPW 
  443. shell command line. However, the old syntax is still supported to provide 
  444. backward compatibility: 
  445.  
  446. DeclareOption  = ':' name [ '+' | '-' ]
  447. DeclareSynonym = ':' name '=' name
  448. SetOption_on   = '+' name | '-' name
  449. SetEquation    = '#' name ['='] value
  450.  
  451.  
  452. ΓòÉΓòÉΓòÉ 4.7. Configuration file ΓòÉΓòÉΓòÉ
  453.  
  454. The configuration file can be used to set the values of options and equations 
  455. (See Chapter Compiler Options and Equations). Every line in the configuration 
  456. file can contain only one compiler option or equation setup directive (See 
  457. Options). Arbitrary spaces are permitted. A character "%" is the comment 
  458. character; it causes the rest of the line to be discarded. Note: the comment 
  459. character can not be used when setting an equation. 
  460.  
  461. A configuration file can contain several LOOKUP equations, which allows us to 
  462. change the search paths, defined in the redirection file: 
  463.  
  464. -LOOKUP = pattern = directory {";" directory}
  465.  
  466. Example of the configuration file: 
  467.  
  468.   % this is a comment line
  469.   % Set equation:
  470.    - BSDef = df
  471.   % Set redirection:
  472.    -lookup = *.mod = mod
  473.    -lookup = *.sym = sym; c:/xds/sym
  474.   % Set predeclared options:
  475.    - RangeCheck -   % turn range checks off
  476.    - M2EXTENSIONS + % allow Modula-2 extensions
  477.   % Declare new options:
  478.    -i80486:+
  479.    -i80386:-
  480.    -i80286:         % is equal to -80286:-
  481.   % Declare synonym:
  482.    -N := checknil
  483.    -N               % disallow NIL checks
  484.   % end of configuration file
  485.  
  486. In the above example the XDS will search for the files with mod and sym 
  487. extensions using the search paths defined in the configuration file. The search 
  488. paths defined in the redirection file will be used for all other extensions. 
  489.  
  490.  
  491. ΓòÉΓòÉΓòÉ 4.8. Filename extensions ΓòÉΓòÉΓòÉ
  492.  
  493. XDS allows you to define what you want to be the standard extensions to each 
  494. particular type of file. For instance you may prefer your Oberon-2 source code 
  495. texts to be extended with a .o2 or a .ob2. 
  496.  
  497. It is wise to either use the traditional extensions or at least the extensions 
  498. which describe the kind of file they refer to, for example, using .def and .mod 
  499. for Modula-2 modules, .ob2 for Oberon-2 modules etc. It is also wise to keep 
  500. the extensions the same across all of your projects. 
  501.  
  502. Certain other factors must also influence your decisions. By tradition, 
  503. Oberon-2 pseudo-definition modules (as created by the browser) are extended 
  504. with a .def. With XDS, this may conflict with the extension used for Modula-2 
  505. definition modules. Therefore, by default the browser uses the extension .odf. 
  506.  
  507. The following filename extensions are usually defined in the configuration 
  508. file: 
  509.  
  510. The appearance of the following table is a known problem and will be improved 
  511. in the final release. 
  512.  
  513. ll def | extension for Modula-2 definition modules 
  514.  mod | extension for Modula-2 implementation modules 
  515.  oberon | extension for Oberon-2 modules 
  516.  bsdef | extension for Oberon-2 pseudo definition modules 
  517.  code | extension for generated code files 
  518.  sym | extension for symbol files 
  519.  
  520. See table ??? for the full list of file extensions. 
  521. Example (file extension entries in xc.cfg): 
  522.  
  523.    -def     = def
  524.    -mod     = mod
  525.    -oberon  = ob2
  526.    -sym     = sym
  527.  
  528.  
  529. ΓòÉΓòÉΓòÉ 4.9. More about XDS environment ΓòÉΓòÉΓòÉ
  530.  
  531. The XDS user environment consists of 
  532.  
  533.      the redirection file 
  534.  
  535.      the configuration file 
  536.  
  537.      a project file for each project 
  538.  
  539.      template files 
  540.  
  541.  The information provided in this section can be applied to any of these files. 
  542.  
  543.  Each file is a sequence of lines. The symbol \ at the end of a line denotes 
  544.  the line continuation. The following features may be used in the files: 
  545.  
  546.      a portable notation for file names (See Working configuration). 
  547.  
  548.      the base directory macro ($!). This macro denotes the directory on which 
  549.       the file containing the macro is placed. 
  550.  
  551.      a set of directives, starting from !. 
  552.  
  553.  The directive has the following syntax (all keywords are case independent): 
  554.  
  555.   Directive = "!" "NEW" SetOption | SetEquation
  556.             | "!" "SET" SetOption | SetEquation
  557.             | "!" "MESSAGE" Expression
  558.             | "!" "IF" Expression "THEN"
  559.             | "!" "ELSIF" Expression "THEN"
  560.             | "!" "ELSE"
  561.             | "!" "END".
  562.   SetOption   = ident ( "+" | "-" ).
  563.   SetEquation = ident = { character }.
  564.  
  565.  The NEW directive declares a new option or equation. The SET directive changes 
  566.  the value of an option or equation. The MESSAGE directive prints a value of 
  567.  expression. The IF directive allows to process or skip portions of files 
  568.  according the value of expression. 
  569.  
  570.   Expression = Simple [ Relation Simple ].
  571.   Simple      = Term { "+" | OR Term }.
  572.   Relation    = "=" | "#" | "<" | ">".
  573.   Term        = Factor { AND Factor }.
  574.   Factor      = "(" Expression ")".
  575.               | String
  576.               | NOT Factor
  577.               | DEFINED name
  578.               | name.
  579.   String      = "'" { character } "'"
  580.               | '"' { character } '"'.
  581.  
  582.  An operand in an expression is either string or equation name or option name. 
  583.  In the case of equation, the value of equation is used. In the case of option, 
  584.  a string "TRUE" or "FALSE" is used. The operator "+" denotes string 
  585.  concatenation. Relation operators perform string comparison. The NOT operator 
  586.  can be applied to any string with value "TRUE" or "FALSE". The DEFINED 
  587.  operator yields "TRUE" if an option or equation name is declared and "FALSE" 
  588.  otherwise. 
  589.  Example of project file 
  590.  
  591.   % check project mode
  592.   !if not defined mode then
  593.     % by default use debug mode
  594.     !new mode = debug
  595.   !end
  596.   % report the project mode
  597.   !message "Making project in the " + mode + "mode"
  598.   % set options according to the mode
  599.   !if mode = debug then
  600.      - gendebug+
  601.      - checkrange+
  602.   !else
  603.      - gendebug-
  604.   !fi
  605.   % specify template file
  606.   - template = $!/templates/xds.tem
  607.   !module Main.ob2
  608.  
  609.  
  610. ΓòÉΓòÉΓòÉ 4.10. Customize XDS messages ΓòÉΓòÉΓòÉ
  611.  
  612. The file xc.msgcontains texts of error messages in the form 
  613.  
  614. <number>       <text>
  615.  
  616. The following is an extract from xc.msg: 
  617.  
  618. 001 illegal character
  619. 002 comment not closed; started at line %d
  620. ...
  621. 042 incompatible assignment
  622. ...
  623.  
  624. Some messages contain format specifiers for additional arguments. I.e. the 
  625. above message comment not closed contains %d specifier to print a line number. 
  626.  
  627. To use a language other than English for compiler messages it is necessary to 
  628. translate the text of the messages, whilst preserving the error numbers and the 
  629. number and order of format specifiers. 
  630.  
  631.  
  632. ΓòÉΓòÉΓòÉ 4.11. XDS and your C compiler ΓòÉΓòÉΓòÉ
  633.  
  634. XDS allows the C libraries to be used in your projects. Different C compilers 
  635. use different naming and calling conventions. It may be necessary to configure 
  636. XDS for your C compiler. See Chapter Configuring XDS for a C Compiler for more 
  637. details. 
  638.  
  639.  
  640. ΓòÉΓòÉΓòÉ 5. Getting Started ΓòÉΓòÉΓòÉ
  641.  
  642. In this and following chapters we assume that XDS is properly installed and 
  643. configured (See Chapter Configuring XDS); the default file extensions are used. 
  644.  
  645. Your XDS package contains a script file to create the working directory. It is 
  646. called xdsuser and placed on the BIN directory. For more information consult 
  647. your readme.1st file from the XDS on-line documentation. 
  648.  
  649.  
  650. ΓòÉΓòÉΓòÉ 5.1. Using the Modula-2 compiler ΓòÉΓòÉΓòÉ
  651.  
  652. In the working directory, use a text editor to create a file called hello.mod, 
  653. containing the following text: 
  654.  
  655. MODULE hello;
  656.  
  657. IMPORT InOut;
  658.  
  659. BEGIN
  660.  InOut.WriteString("Hello World");
  661.  InOut.WriteLn;
  662. END hello.
  663.  
  664. Type 
  665.  
  666.  xc hello.mod 
  667.  
  668. xc will know that the Modula-2 compiler should be invoked for the source file 
  669. with the extension .mod. The compiler heading line will appear: 
  670.  
  671. Modula-2 version [code generator] "hello.mod"
  672.  
  673. showing which compiler has been invoked (including its version number), which 
  674. code generator is being used (in square brackets) and its version, and finally 
  675. the name of the source file it has been asked to compile. 
  676.  
  677. Assuming that you have correctly typed the source file, after compilation, the 
  678. compiler displays 
  679.  
  680. errors: 0(0)  lines: 15  time: 1.09
  681.  
  682. showing the number of errors, the number of source lines and compilation time. 
  683.  
  684. Note: The XDS compiler reports are user configurable. If the statements above 
  685. do not appear, check that the DECOR equation value contains `c' (compiler 
  686. heading) and `r' (report) letters. 
  687.  
  688.  
  689. ΓòÉΓòÉΓòÉ 5.2. Using the Oberon-2 compiler ΓòÉΓòÉΓòÉ
  690.  
  691. In our bilingual system the Modula-2 source code just shown is also perfectly 
  692. valid as the Oberon-2 code. XDS allows you to use Modula-2 libraries when 
  693. programming in Oberon-2 (in our case InOut library). 
  694.  
  695. As in Modula-2, this source code in Oberon-2 constitutes a top-level module or 
  696. program module. Unlike Modula-2, there is no syntactic distinction between a 
  697. top-level module and any other service module. Oberon-2 compiler must be 
  698. specifically told that this is a program module by using the option MAIN. Copy 
  699. the source file to the file hello.ob2 and type: 
  700.  
  701.  xc hello.ob2 +MAIN 
  702.  
  703. The same sequence of reports will occur as that of the Modula-2 compiler, but 
  704. the Oberon-2 compiler will also report whether a new symbol file was generated 
  705. or not. It is possible to override the default source file extension: 
  706.  
  707.  xc hello.mod +O2 +MAIN 
  708.  
  709. In this case, the Oberon-2 compiler will be invoked regardless of the file 
  710. extension. 
  711.  
  712.  
  713. ΓòÉΓòÉΓòÉ 5.3. Error reporting ΓòÉΓòÉΓòÉ
  714.  
  715. If either compiler detects an error in your code, an error description will be 
  716. displayed. In most cases a copy of the source line will also be shown with a 
  717. dollar sign "$" placed directly before the point at which the error occurred. 
  718. The format by which XDS reports errors is user configurable (See Error message 
  719. format specification), by default it includes the file name, the line number 
  720. and column in which the error occurred and an error kind, which can be [E]rror, 
  721. [W]arning or [F]ault. 
  722. Example 
  723.  
  724. (hello.m 6,33) [E] expected symbol  ")"
  725.  InOut.WriteString("Hello World"$;
  726. (hello.m 7,2) [E] expected symbol  ";"
  727.  $InOut.WriteLn;
  728.  
  729.  
  730. ΓòÉΓòÉΓòÉ 5.4. Running a program ΓòÉΓòÉΓòÉ
  731.  
  732. After compilation of all modules composing your project you have to link the 
  733. program. The xdsuser script creates the xl script that can be used to link a 
  734. simple program. 
  735.  
  736.    xl hello
  737.  
  738. If your project contains more than one module, we recommend to write a project 
  739. file (See Project files) and use appropriate template file (See Template 
  740. files). The following project file contains all necessary settings: 
  741.  
  742. % debug ON
  743. -gendebug+
  744. -genhistory+
  745. -lineno+
  746. % specify template file
  747. -template = xds.tem
  748. % specify a name of a linker response file
  749. -mkfname = tmp
  750. -mkfext  = mkf
  751. % force generation of the response file
  752. -makefile+
  753. % linker command line
  754. -link = "xlink @%s",mkfname#mkfext;
  755. % main module of the program
  756. !module hello.mod
  757.  
  758. It specifies the template file to use (xds.tem), the name of the linker 
  759. response file (tmp.mkf) and linker command line. 
  760.  
  761. After successful compilation of the whole project the compiler creates the 
  762. linker response file and then executes the command line, specied by the LINK 
  763. equation. The xds.tem template file defines a template for a linker response 
  764. file: 
  765.  
  766. /sys=C
  767. !if gendebug then
  768.   /debug
  769. !end
  770. !if defined stacklimit then
  771.   ! "/stack=%s\n",stacklimit;
  772. !else
  773.   /stack=128K
  774. !end
  775. ! { main : "/name=%s\n",#>exeext; }
  776. ! { main imp oberon : "%s\n",#>objext }
  777. ! "%s\n","libxds"#"lib"
  778.  
  779. An iterator of the form 
  780.  
  781. { main imp oberon : "%s\n",#>objext }
  782.  
  783. will insert the names of object files for all modules constituting your 
  784. program. The following invocation 
  785.  
  786.  xc hello.prj =p 
  787.  
  788. will compile modules constituting the project (if required) and then execute 
  789. the linker. See Template files for the full description of template files. See 
  790. also the project files, generated by the xdsuser script. 
  791.  
  792.  
  793. ΓòÉΓòÉΓòÉ 5.5. Debugging a program ΓòÉΓòÉΓòÉ
  794.  
  795. XDS compilers generate debug information in the CodeView format and allows one 
  796. to use any debugger compatible with this format. However, the postmorten 
  797. historyfeature of XDS run-time support may be used in may cases instead of 
  798. debugger. To enable this feature the option LINENOshould be set for all modules 
  799. in the program and the option GENHISTORYfor the main module of the program; the 
  800. linker (xlink) 
  801.  
  802. should be called with the /debug option. 
  803.  
  804. If your program is compiled in this mode, the run-time system will print a 
  805. stack of procedure calls (a file name and a line number) on abnormal 
  806. termination of your program. 
  807. Example 
  808.  
  809. MODULE test;
  810.  
  811. PROCEDURE Div(a,b: INTEGER): INTEGER;
  812. BEGIN
  813.   RETURN a DIV b
  814. END Div;
  815.  
  816. PROCEDURE Try;
  817.   VAR res: INTEGER;
  818. BEGIN
  819.   res:=Div(1,0);
  820. END Try;
  821.  
  822. BEGIN
  823.   Try;
  824. END test.
  825.  
  826. When this program is running, the exception is raised and the run-time system 
  827. prints the exception location and a stack of procedure calls. [3] 
  828.  
  829. #RTS: No exception handler #6: zero or negative divisor
  830. ------------------------------------------------------------
  831. Source file                        LINE  OFFSET  PROCEDURE
  832. ------------------------------------------------------------
  833. "test.mod"                            5 0000000D
  834. "test.mod"                           11 00000024
  835. "test.mod"                           15 00000051
  836.  
  837. The exception was raised in line 5 of test.mod, the Div procedure was called 
  838. from line 11, while the Try procedure was called from line 15 (module body). 
  839.  
  840. In some cases, the history may contain wrong lines. See History for further 
  841. details. 
  842.  
  843.  
  844. ΓòÉΓòÉΓòÉ 5.6. Optimizing a program ΓòÉΓòÉΓòÉ
  845.  
  846. Unlike many other compilers, XDS always produces optimized code. There are no 
  847. such things in XDS as levels of optimization. It is sometimes the case with 
  848. other compilers that unoptimized version of the program works properly, but 
  849. optimized one does not. If a compiler have a dozen of optimization options it 
  850. may be extremely difficult to debug the compiler itself. A compiler 
  851. manufacturer has to check all possible combinations of options. It is not the 
  852. case with XDS. The only option that may disable some of optimizations is the 
  853. the GENDEBUG option. 
  854.  
  855. There are still several ways to control the generated code. First of all you 
  856. have to choose what is more important for you: fast code or small code. By 
  857. default, the option SPACE is set off, forcing the compiler to favor the fast 
  858. code. 
  859.  
  860. To get the maximum performance do the following: 
  861.  
  862.      turn SPACE off 
  863.  
  864.      turn GENDEBUG off 
  865.  
  866.      turn ALIGNMENT on 
  867.  
  868.      turn run-time checks and overflow checks off 
  869.  
  870.  It is possible not to turn run-time checks off in the product versions of your 
  871.  programs, because the code generator usually removes redundant checks. An 
  872.  average program with all run-time checks turned off runs only 10-15% faster 
  873.  (the code size is usually significantly smaller). 
  874.  
  875.  Two options should be used with care: 
  876.  
  877.      the PROCINLINE option allows the compiler to expand procedures in-line. 
  878.       As a rule switching the option ON leads to faster but bigger code. 
  879.       However, the effect of this option depends on your programming style 
  880.       (size of procedures, etc). 
  881.  
  882.      the NOPTRALIAS option allows the compiler to assume that there is no 
  883.       pointer aliasing, i.e. there are no pointers bounded to non-structure 
  884.       variables. The code quality is better if the option is ON. 
  885.  
  886.  Example of project file for maximum performance 
  887.  
  888.   -alignment+          % is unnecessary under Linux
  889.   -noptralias+
  890.   -procinline+
  891.   -space
  892.  
  893.   -checkindex
  894.   -checkrange
  895.   -checknil
  896.   -ioverflow
  897.   -coverflow
  898.   -gendebug
  899.   -genhistory
  900.   -lineno
  901.   !module Foo.mod
  902.  
  903.  In some cases, it may be better to set different options for different modules 
  904.  in your program. See dry.mod from XDS samples. 
  905.  
  906.  
  907. ΓòÉΓòÉΓòÉ 6. Using XDS ΓòÉΓòÉΓòÉ
  908.  
  909.  
  910. ΓòÉΓòÉΓòÉ 6.1. Invoking XDS ΓòÉΓòÉΓòÉ
  911.  
  912. The XDS Modula-2 and Oberon-2 compilers are combined together with additional 
  913. operation modes into a single utility, xc. When invoked without parameters, the 
  914. utility outputs the help information. 
  915.  
  916. xc is invoked from the command line of the following form 
  917.  
  918.  xc { OPERATION MODE | OPTION | NAME } 
  919.  
  920. where NAME for different operation modes is a module name, file name or a 
  921. project name. See ??? for the full description of operation modes. 
  922.  
  923. OPTION is a compiler setup directive (See Options). On the command line all 
  924. options are applied to all operands. On some platforms it may be necessary to 
  925. enclose some setup directive in quotation marks, e.g. `enable option' directive 
  926. under MacOS/MPW shell: 
  927.  
  928.  xc hello.mod '-checkindex+' 
  929.  
  930. See Chapter Compiler Options and Equations for the list of all compiler options 
  931. and equations. 
  932.  
  933.  
  934. ΓòÉΓòÉΓòÉ 6.1.1. Precedence of compiler options ΓòÉΓòÉΓòÉ
  935.  
  936. The xc utility can receive its options from the 
  937.  
  938.    1. configuration file xc.cfg (See Configuration file) 
  939.  
  940.    2. command line (See ???) 
  941.  
  942.    3. project file (if present) (See Project files) 
  943.  
  944.    4. inline in a source text (not all options can be used there) (See Source 
  945.       code directives) 
  946.  
  947.  At any point during operation, the last value of an option will be in effect. 
  948.  Thus, if the equation OBERON was set to .ob2 in the configuration file, but 
  949.  then set to .o2 on the command line, then XDS will recognize .o2 as the 
  950.  default Oberon-2 extension. 
  951.  
  952.  
  953. ΓòÉΓòÉΓòÉ 6.2. XDS operation modes ΓòÉΓòÉΓòÉ
  954.  
  955. XDS has the following operation modes: 
  956.  
  957. The appearance of the following table is a known problem and will be improved 
  958. in the final release. 
  959.  
  960. |l|l|Mode | Meaning 
  961.  COMPILE | Compile all modules given on the command line 
  962.  PROJECT | Make all projects given on the command line 
  963.  MAKE | Check dependencies and recompile 
  964.  GEN | Generate makefile for all projects 
  965.  BROWSE | Extract definitions from symbol files 
  966.  HELP | Print help and abort the program 
  967.  
  968. Both the PROJECT and MAKE modes have two optional operation submodes: BATCH and 
  969. ALL. Two auxilary operation submodes - OPTIONS and EQUATIONS can be used to 
  970. inspect the set of compiler options and equations and their values. 
  971.  
  972. From the command line, the compiler mode is set with '=' followed by the 
  973. required mode. Only the unique portion of a name may be specified. Operation 
  974. mode names are not case sensitive, thus 
  975.  
  976.         =PROJECT   is equivalent to   =p
  977.         =BROWSE    is equivalent to   =Bro
  978.  
  979. Operation modes and options can be placed everywhere in the command line. Thus 
  980. two following invokations are equal to each other: 
  981.  
  982.  xc =make hello.mod =all -checknil+ 
  983.  xc -checknil+ =a =make hello.mod 
  984.  
  985.  
  986. ΓòÉΓòÉΓòÉ 6.2.1. COMPILE mode ΓòÉΓòÉΓòÉ
  987.  
  988.  xc [=compile] { FILENAME | OPTION } 
  989.  
  990. COMPILE is the default mode, and can be invoked simply by supplying xc with a 
  991. source module(s) to compile. If xc is invoked without a given mode, COMPILE 
  992. mode is assumed. In order to determine which compiler should be used, xc looks 
  993. at the extensions of the given source files. The default mapping of extensions 
  994. is given below : 
  995.  
  996. The appearance of the following table is a known problem and will be improved 
  997. in the final release. 
  998.  
  999. lcl .mod |-| Modula-2 implementation module 
  1000.  .def |-| Modula-2 definition module 
  1001.  .ob2 |-| Oberon-2 module 
  1002.  
  1003. For example: 
  1004.  
  1005.  xc hello.mod 
  1006.  
  1007. will invoke the Modula-2 compiler, whilst: 
  1008.  
  1009.  xc hello.ob2 
  1010.  
  1011. will invoke the Oberon-2 compiler. 
  1012.  
  1013. The user is able to reconfigure the extension mapping (See Filename 
  1014. extensions). It is also possible to override this extension mapping from the 
  1015. command line using options M2 and O2 (See ???): 
  1016.  
  1017.  xc hello.mod +o2 (* invokes O2 compiler *) 
  1018.  xc hello.ob2 +m2 (* invokes M2 compiler *) 
  1019.  
  1020.  
  1021. ΓòÉΓòÉΓòÉ 6.2.2. MAKE mode ΓòÉΓòÉΓòÉ
  1022.  
  1023.  xc =make [=batch] [=all] { FILENAME | OPTION } 
  1024.  
  1025. In the MAKE mode the compiler calculates module dependencies (using IMPORT 
  1026. clauses) and then recompiles all modules that are necessary. Starting from the 
  1027. files on the command line, it tries to find an Oberon module or a definition 
  1028. and implementaion module for each imported module. It then does the same for 
  1029. each of the imported modules until all modules are located. Note that a search 
  1030. is made for source files only. If a source file is not found, the imported 
  1031. modules will not be appended to the project. Usually, only a Modula-2 program 
  1032. module or an Oberon-2 top-level module should be given on the command line. See 
  1033. section Make strategy for more details. 
  1034.  
  1035. When all modules are gathered, XDS performs an action according to the 
  1036. operation submode. If the BATCH submode is specified, XDS creates a batch file 
  1037. of all necessary compilations, rather than actually calling the compilers and 
  1038. compiling the source code (See BATCH submode). 
  1039.  
  1040. If the ALL submode is specified, all gathered files are recompiled, otherwise 
  1041. XDS calculates conditions for recompilation and recompiles only those files 
  1042. that are necessary. The smart recompilation algorithm is described in Smart 
  1043. recompilation. 
  1044.  
  1045.  
  1046. ΓòÉΓòÉΓòÉ 6.2.3. PROJECT mode ΓòÉΓòÉΓòÉ
  1047.  
  1048.  xc =project [=batch] [=all] { PROJECTFILE | OPTION } 
  1049.  
  1050. The PROJECT mode is essentially the same as the MAKE mode except that the 
  1051. modules to be `made' are provided in a project file. A project file specifies a 
  1052. set of options and a list of modules. See Project files for further details. As 
  1053. in the MAKE mode, ALL and BATCH submodes can be used. 
  1054.  
  1055. If a file extension of a project file is omitted, XDS will use an extension 
  1056. given by the equation PRJEXT (.prj by default). 
  1057.  
  1058. It may be desirable to compile a single module in the environment specified in 
  1059. the project file. It can be done with the PRJ equation in the COMPILE operation 
  1060. mode. 
  1061.  
  1062.  xc -prj=myproject MyModule.mod 
  1063.  
  1064.  See also 
  1065.  
  1066.      MAKE operation mode: MAKE mode 
  1067.  
  1068.      Make strategy: Make strategy 
  1069.  
  1070.      Smart recompilation: Smart recompilation 
  1071.  
  1072.  
  1073. ΓòÉΓòÉΓòÉ 6.2.4. GEN mode ΓòÉΓòÉΓòÉ
  1074.  
  1075.  xc =gen { PROJECTFILE | OPTION } 
  1076.  
  1077. The GEN operation mode allows one to generate a file containing information 
  1078. about your project. The most important usage is to generate a linker response 
  1079. file (See Running a program). This operation mode can also be used to obtain an 
  1080. additional information about your project, e.g. a list of all modules, import 
  1081. lists, etc. 
  1082.  
  1083. A so-called template file is used in this mode. A template file name is 
  1084. determined by the TEMPLATE equation.A template file is a text file, some lines 
  1085. of which are 
  1086.  
  1087. marked with an assigned symbol. All the lines which are not marked are copied 
  1088. to output. The marked lines are processed in a special way (See Template 
  1089. files). 
  1090.  
  1091. XDS will create a file with a name determined by either the compiler option 
  1092. MKFNAME or the project file name. A file name is then concatenated with the 
  1093. extension specified by the equation MKFEXT. 
  1094.  
  1095.  
  1096. ΓòÉΓòÉΓòÉ 6.2.5. BROWSE mode ΓòÉΓòÉΓòÉ
  1097.  
  1098.  xc =browse { MODULENAME | OPTION } 
  1099.  
  1100. The BROWSE operation mode allows one to generate a pseudo definition module for 
  1101. an Oberon-2 module. In this mode XDS scans the symbol file and produces a 
  1102. Modula-2-like definition module which contains all client-visible objects. 
  1103.  
  1104. The configuration option BSDEF (See Equations) specifies the extension of a 
  1105. generated file. If this option is not set, then the default extension (.odf) 
  1106. will be used. 
  1107.  
  1108. Options BSCLOSURE and BSREDEFINE can be used to control the form of a generated 
  1109. file. Note: the BSTYLE equation (described in Creating a definition) is ignored 
  1110. in this operation mode, and the browse style is always set to DEF. 
  1111.  
  1112. The MAKEDEF option (See Creating a definition) provides an alternative method 
  1113. of producing pseudo definition modules, preserving so-called exported comments 
  1114. if necessary. 
  1115.  
  1116.  
  1117. ΓòÉΓòÉΓòÉ 6.2.6. ALL submode ΓòÉΓòÉΓòÉ
  1118.  
  1119. In both PROJECT and MAKE modes, XDS checks the time stamps of the files 
  1120. concerned and recompiles only those files that are necessary. If ALL submode is 
  1121. set, the time stamps are ignored, and all files are compiled. 
  1122.  
  1123.  
  1124. ΓòÉΓòÉΓòÉ 6.2.7. BATCH submode ΓòÉΓòÉΓòÉ
  1125.  
  1126. In the BATCH submode, XDS creates a batch file of all necessary compilation, 
  1127. rather than actually calling the compilers and compiling the source code. 
  1128.  
  1129. A batch file is sequence of lines beginning with the compiler name, followed by 
  1130. module names to recompile. 
  1131.  
  1132. XDS will create a batch file with a name determined by either: 
  1133.  
  1134.    1. The compiler option BATNAME (see Equations) 
  1135.  
  1136.    2. The project file name (if given) 
  1137.  
  1138.    3. The name out (if no name can be determined by above). 
  1139.  
  1140.  Batch file name is then concatenated with the batch file extension specified 
  1141.  by the equation BATEXT (.bat by default). 
  1142.  
  1143.   See also 
  1144.  
  1145.      option LONGNAME (???) 
  1146.  
  1147.      equation BATWIDTH (Equations) 
  1148.  
  1149.  
  1150. ΓòÉΓòÉΓòÉ 6.2.8. OPTIONS submode ΓòÉΓòÉΓòÉ
  1151.  
  1152. The OPTIONS submode allows you to inspect the values of options which are set 
  1153. in the configuration file, project file and on the command line. It can be used 
  1154. together with COMPILE, MAKE and PROJECT modes. 
  1155.  
  1156. The following invocation will print (to the standard output) the list of all 
  1157. defined options, including all pre-declared options, all options declared in 
  1158. the configuration file, in the project file my.prj and on the command line (xyz 
  1159. option): 
  1160.  
  1161.  xc =options -prj=my.prj -xyz:+ 
  1162.  
  1163. In the PROJECT mode options are listed for each project file given on the 
  1164. command line. 
  1165.  
  1166.  
  1167. ΓòÉΓòÉΓòÉ 6.2.9. EQUATIONS submode ΓòÉΓòÉΓòÉ
  1168.  
  1169. The EQUATIONS submode allows you to inspect the values of options which are set 
  1170. in the configuration file, project file and on the command line. It can be used 
  1171. together with COMPILE, MAKE and PROJECT modes. 
  1172.  
  1173.  
  1174. ΓòÉΓòÉΓòÉ 6.3. Files generated during compilation ΓòÉΓòÉΓòÉ
  1175.  
  1176. When applied to a file which contains a module name, the compilers produce the 
  1177. following files. 
  1178. Modula-2 compiler 
  1179.  
  1180. When applied to a definition module, the Modula-2 compiler produces a symbol 
  1181. file(name.sym). The symbol file contains an information necessary for the 
  1182. compilation of a module which imports a module name. 
  1183.  
  1184. When applied to an implementation module or top level module, the Modula-2 
  1185. compiler produces an object file (name.obj). 
  1186. Oberon-2 compiler 
  1187.  
  1188. For all compiled modules, the Oberon-2 compiler produces a symbol file 
  1189. (name.sym) and an object file (name.obj). The symbol file(name.sym) contains an 
  1190. information necessary for the compilation of a module which imports a module 
  1191. name. If, during compilation, the compiler needs to overwrite an existing 
  1192. symbol file, it will only do so if the option DEF (see ???) has been set. 
  1193. Examples 
  1194.  
  1195. The appearance of the following table is a known problem and will be improved 
  1196. in the final release. 
  1197.  
  1198. l|l Command Line | Generated files 
  1199.  xc Example.def | Example.sym 
  1200.  xc Example.mod | Example.obj 
  1201.  xc Windows.ob2 +DEF | Windows.sym 
  1202.  | Windows.obj 
  1203.  
  1204.  
  1205. ΓòÉΓòÉΓòÉ 6.4. Project files ΓòÉΓòÉΓòÉ
  1206.  
  1207. A project file has the following structure: 
  1208.  
  1209.      {OPTION}
  1210.      {!module {FILENAME}}
  1211.  
  1212. where OPTIONs are the compiler setup directives (See Options), defining options 
  1213. and equations that all modules should be compiled with, and FILENAMEs are 
  1214. modules of the project. It should be noted that XDS recursively looks at all 
  1215. the given files for any imported modules. Thus, usually, a project file would 
  1216. consist of one single module, the main program module. At least one module 
  1217. should be specified in a project file. 
  1218.  
  1219. Every line in a project file can contain only one setup directive. A character 
  1220. "%" is the comment character. It causes the rest of the line to be discarded. 
  1221. Note: the comment character can not be used in setting an equation. 
  1222.  
  1223. XDS gives you complete freedom where to set options, equations and redirection 
  1224. directives. However, it is advisable to specify only those settings in the 
  1225. configuration and redirection files which are applied to all your projects, and 
  1226. use project files to specify all project-dependent options and redirection 
  1227. directive. 
  1228.  
  1229. A project file can contain several LOOKUP equations, which allows one to 
  1230. redefine some search paths. 
  1231. Example Project File: 
  1232.  
  1233. -mod = mod
  1234. -checkindex+
  1235. -lookup = *.mod = mod
  1236. -lookup = *.sym = sym; c:/xds/sym
  1237. !module hello
  1238.  
  1239. In the above example, XDS will search files with .mod and .sym extensions using 
  1240. search paths specified in the project file. For all other extensions, search 
  1241. paths, specified in the redirection file or configuration file or on the 
  1242. command line will be used. 
  1243.  
  1244. A project file is specified explicitly in the PROJECT and GEN operation modes. 
  1245. In these cases all options and equations are set and then XDS proceeds the 
  1246. module list to gather all modules constituting a project (See Make strategy). 
  1247.  
  1248. In the MAKE and COMPILE operation mode, a project file can be specified using 
  1249. the PRJ equation. In these cases the module list is ignored, but all options 
  1250. and equations are set. 
  1251.  
  1252. The following command line forces XDS to compile the module hello.mod in the 
  1253. COMPILE operation mode using options and equations specified in the project 
  1254. file hello.prj: 
  1255.  
  1256.  xc hello.mod -prj=hello.prj 
  1257.  
  1258.  
  1259. ΓòÉΓòÉΓòÉ 6.5. Make strategy ΓòÉΓòÉΓòÉ
  1260.  
  1261. All information presented here concerns MAKE, PROJECT and GEN operation modes. 
  1262. In these modes XDS builds a set of all modules that constitute the project, 
  1263. starting from the modules specified in a project file (PROJECT and GEN) or on a 
  1264. command line (MAKE). 
  1265.  
  1266. The MAKE mode will be used in most of the following examples, but the comments 
  1267. will concern both to the PROJECT and GEN modes. 
  1268.  
  1269. At first, XDS tries to find all given modules according to the following 
  1270. strategy: 
  1271.  
  1272.      If both a filename extension and a path to the a file are specified, it 
  1273.       checks if the given file exists. 
  1274.  
  1275.        xc =make mod\hello.mod 
  1276.  
  1277.      If a filename extension is specified, the file will try to find a file 
  1278.       using search paths. 
  1279.  
  1280.        xc =make hello.mod 
  1281.  
  1282.      If a filename extension is not specified, XDS will try to find a file 
  1283.       with the Oberon-2 extension, Modula-2 module and definition extensions. 
  1284.  
  1285.        xc =make hello 
  1286.  
  1287.       An error will be raised if there is more than one source file, e.g. both 
  1288.       hello.ob2 and hello.mod files are accessible. 
  1289.  
  1290.  Starting from the given files XDS tries to find an Oberon module or a pair - a 
  1291.  definition and implementation module for each imported module. It then tries 
  1292.  to do the same for each of the imported modules until all modules are located. 
  1293.  For all modules XDS checks the correspondence between the file name extensions 
  1294.  and a kind of the module. 
  1295.  
  1296.  
  1297. ΓòÉΓòÉΓòÉ 6.6. Smart recompilation ΓòÉΓòÉΓòÉ
  1298.  
  1299. In the PROJECT and MAKE mode, XDS offers smart recompilation of all modules in 
  1300. a project which are inconsistent with the available source code files. XDS uses 
  1301. a file modification time to determine which file has been changed. For every 
  1302. module the decision is made (to recompile or not) only after the decision is 
  1303. made for all modules on which it depends. A file is compiled if one or more of 
  1304. the following conditions is true: 
  1305.  
  1306.  definition module 
  1307.  
  1308.                the symbol file is missing 
  1309.  
  1310.                the symbol file is present but the modification date is earlier 
  1311.                 than that of the source file or one of the imported symbol 
  1312.                 files 
  1313.  
  1314.  implementation module 
  1315.  
  1316.                the code file is missing 
  1317.  
  1318.                the code file is present but the file modification date is 
  1319.                 earlier than that of the source file or one of the imported 
  1320.                 symbol files (including its own symbol file) 
  1321.  
  1322.  program module 
  1323.  
  1324.                the code file is missing 
  1325.  
  1326.                the code file is present but the file modification date is 
  1327.                 earlier than that of the source file or one of the imported 
  1328.                 symbol files 
  1329.  
  1330.  Oberon-2 module 
  1331.  
  1332.                the symbol file is missing 
  1333.  
  1334.                the symbol file is present but the modification date is earlier 
  1335.                 than that of one of the imported symbol files 
  1336.  
  1337.                the code file is missing 
  1338.  
  1339.                the code file is present but the file modification date is 
  1340.                 earlier than that of the source file or one of the imported 
  1341.                 symbol files 
  1342.  
  1343.  When the VERBOSE option is ON, XDS reports why the module is recompiled. Note: 
  1344.  if an error occurs when a definition or Oberon-2 module is compiled, all 
  1345.  client modules will not be compiled at all. 
  1346.  
  1347.  
  1348. ΓòÉΓòÉΓòÉ 6.7. Template files ΓòÉΓòÉΓòÉ
  1349.  
  1350. A template file is used for defining the structure of the file generated in the 
  1351. GEN operation mode or PROJECT mode, if the option MAKEFILE is ON. XDS copies 
  1352. lines from the template file into the output file verbatim, unless the lines 
  1353. are marked as requiring further attention. A single character (attention mark) 
  1354. is specified by the equation ATTENTION(default is '!'). 
  1355.  
  1356. A marked line (or template) has the following format The same syntax is used in 
  1357. the LINK equation. : 
  1358.  
  1359. Template  = { Sentence }.
  1360. Sentence  = Item { "," Item } ";" | Iterator.
  1361. Item      = Atom | [ Atom | "^" ] "#" [ Extension ].
  1362. Atom      = String | name.
  1363. String    = '"' { character } '"'
  1364.           | "'" { character } "'".
  1365. Extension = [ ">" ] Atom.
  1366. Iterator  = "{" Set ":" { Sentence } "}".
  1367. Set       = { Keyword | String }
  1368. Keyword   = DEF | IMP | OBERON | MAIN
  1369.           | C | HEADER | ASM | OBJ.
  1370.  
  1371. A name should be the name of equation. Not more than three items may be used in 
  1372. a sentence. A first item in a sentence is a format string, while others are 
  1373. arguments. 
  1374.  
  1375. In the simplest form a template file can be used to output a value of an 
  1376. equation. For example, if a template file contains the line 
  1377.  
  1378. ! "Current project is %s.\n",prj;
  1379.  
  1380. and the project prj\test.prj is processed, the output will contain the line 
  1381.  
  1382. Current project is prj/test.prj.
  1383.  
  1384. Note: the following line 
  1385.  
  1386. ! prj;
  1387.  
  1388. is valid, but will produce unexpected result under MS-DOS or Windows: 
  1389.  
  1390. prj     est.prj
  1391.  
  1392. because \t in the format string will be replaced by tabulator character. Use 
  1393. the following form instead: 
  1394.  
  1395. ! "%s",prj;
  1396.  
  1397. The "#" operator creates a file name from the namegiven by either equation 
  1398. value or literal string and extension. A file names is build according to XDS 
  1399. search paths. For example, if a path to the XDS library directory is defined: 
  1400.  
  1401. *.lib = \xds\lib
  1402.  
  1403. the line 
  1404.  
  1405. ! "libxds"#"lib"
  1406.  
  1407. will produce 
  1408.  
  1409. \xds\lib\libxds.lib
  1410.  
  1411. If the modifier ">" is specified, XDS assumes that the file with this name is 
  1412. output file and builds its name according to the strategy for output files (See 
  1413. Redirection file). The form in which a name or extension is omitted can be used 
  1414. in an iterator only. 
  1415.  
  1416. Iterators are used to generate a text for all modules from the specified set. 
  1417. Sentences inside the first level brackets are repeated for all modules of the 
  1418. project, while sentences inside the second level are repeated for all imported 
  1419. modules. A set is a sequence of keywords and strings. Each string denotes a 
  1420. specific module, while a keyword denotes all modules of specific kind. The 
  1421. meaning of keywords is the following: 
  1422.  
  1423. The appearance of the following table is a known problem and will be improved 
  1424. in the final release. 
  1425.  
  1426. |l|p7.8cm| Keyword |Meaning 
  1427.  DEF | Modula-2 definition module 
  1428.  IMP | Modula-2 implementation module 
  1429.  MAIN | Modula-2 program module or Oberon module, marked as MAIN 
  1430.  OBERON | Oberon module 
  1431.  C | C source text 
  1432.  HEADER | C header file 
  1433.  ASM | assembler source text 
  1434.  OBJ | object file 
  1435.  
  1436. The following template file can be used for listing all modules in the project 
  1437. for which source files are available: 
  1438.  
  1439. ! { imp oberon main: "%s ",#; }
  1440.  
  1441. For example, consider a program module A, which imports modules B and C. B 
  1442. itself imports D. All modules are written in Modula-2. Thus: 
  1443.  
  1444.             A
  1445.           /   \
  1446.          B     C
  1447.          |
  1448.          D
  1449.  
  1450. The template given above would generate the following line: 
  1451.  
  1452. A.mod B.mod C.mod D.mod
  1453.  
  1454. To output both definition and implementation modules, one can write: 
  1455.  
  1456. ! { def : "%s ",#; }
  1457. ! { imp oberon main: "%s ",#; }
  1458.  
  1459. Then the output will be: 
  1460.  
  1461. B.def C.def D.def A.mod B.mod C.mod D.mod
  1462.  
  1463. The next template file can be used for listing all modules in the project 
  1464. together with their import: 
  1465.  
  1466. ! { imp main: "%s\n",#; { def: "  %s\n",#; } }
  1467.  
  1468. The form ^# may be used in the second level iterator to out a current name of 
  1469. the fisrt level iterator. 
  1470.  
  1471. The XDS distribution contains a template file xds.tem which can be used to 
  1472. produce a linker response file (See Running a program). 
  1473.  
  1474.  
  1475. ΓòÉΓòÉΓòÉ 7. Compiler Options and Equations ΓòÉΓòÉΓòÉ
  1476.  
  1477. A rich set of XDS options allows one to control the source language, code 
  1478. generated and internal limits and settings. We distinguish between boolean 
  1479. options (or just options) and equations. An option can be set ON (TRUE) or OFF 
  1480. (FALSE), while an equation value is a string. 
  1481.  
  1482.  
  1483. ΓòÉΓòÉΓòÉ 7.1. Options ΓòÉΓòÉΓòÉ
  1484.  
  1485. Options control the process of compilation, including language extensions, 
  1486. run-time checks and code generation. An option can be set ON (TRUE) or OFF 
  1487. (FALSE). 
  1488.  
  1489. A compiler setup directive (See Options) is used to set the option value or to 
  1490. declare it. 
  1491.  
  1492. Options may be set in the configuration file (See Configuration file), on the 
  1493. command line (See ???), in the project file (See Project files) or in the 
  1494. source text (See Source code directives). At any point of operation, the last 
  1495. value of an option is in effect. 
  1496.  
  1497. All options are listed in the section Description of options, see also tables 
  1498. ??? (page table:opt:check), ??? (page table:opt:ext), ??? (page table:opt:code) 
  1499. and Options (page table:opt:misc). 
  1500.  
  1501. [htbp] 
  1502.  
  1503. The appearance of the following table is a known problem and will be improved 
  1504. in the final release. 
  1505.  
  1506. |l|l|Option |Meaning 
  1507.  ASSERT | enable ASSERT generation 
  1508.  CHECKDINDEX | check of dynamic array bounds 
  1509.  CHECKDIV | check for a positive divisor 
  1510.  | (DIV and MOD) 
  1511.  CHECKINDEX | check of static array bounds 
  1512.  CHECKNIL | NIL pointer dereference check 
  1513.  CHECKPROC | check of a formal procedure call 
  1514.  CHECKRANGE | range checks 
  1515.  | (range types and enumerations) 
  1516.  CHECKSET | range check of set operations 
  1517.  CHECKTYPE | dynamic type guards (Oberon-2 only) 
  1518.  COVERFLOW | cardinal overflow check 
  1519.  IOVERFLOW | integer overflow check 
  1520.  
  1521. Run-time checks 
  1522.  
  1523. [htbp] 
  1524.  
  1525. The appearance of the following table is a known problem and will be improved 
  1526. in the final release. 
  1527.  
  1528. |l|p7cm|Option |Meaning 
  1529.  M2ADDTYPES | add SHORT and LONG types 
  1530.  M2BASE16 | use 16-bits basic types in Modula-2 
  1531.  M2CMPSYM | compare symbol files in Modula-2 
  1532.  M2EXTENSIONS | enables Modula-2 extensions 
  1533.  M2UNPACKTYPES | forces to use unpack form of some types 
  1534.  O2EXTENSIONS | enables Oberon-2 extensions 
  1535.  O2ISOPRAGMA | enables ISO Modula-2 pragmas in Oberon 
  1536.  O2NUMEXT | enables Oberon-2 scientific extensions 
  1537.  STORAGE | enables the default memory management in Modula-2 
  1538.  
  1539. Source language control options 
  1540.  
  1541. [htbp] 
  1542.  
  1543. The appearance of the following table is a known problem and will be improved 
  1544. in the final release. 
  1545.  
  1546. |l|p7cm| Option |Meaning 
  1547.  __GEN_C__ | ANSI C code generation 
  1548.  __GEN_X86__ | code generation for 386/486/Pentium 
  1549.  ALIGNMENT | align data 
  1550.  DEFLIBS | put the default library names into object files 
  1551.  GENDEBUG | generate code in the debug mode 
  1552.  GENFRAME | always generate a procedure frame 
  1553.  GENHISTORY | enables postmorten history 
  1554.  GENPTRINIT | generate a local pointer initialization 
  1555.  LINENO | generate line numbers in object files 
  1556.  NOPTRALIAS | ignore the pointer aliasing 
  1557.  PROCINLINE | enables in-line procedure's expansion 
  1558.  SPACE | code size is more important then speed 
  1559.  VERSIONKEY | append version key to the module initialization 
  1560.  
  1561. Code generator control options 
  1562.  
  1563. [htbp] 
  1564.  
  1565. The appearance of the following table is a known problem and will be improved 
  1566. in the final release. 
  1567.  
  1568. |l|l| Option | Meaning 
  1569.  BSCLOSURE | browse control option 
  1570.  BSREDEFINE | browse control option 
  1571.  DEF | permission to change a symbol file 
  1572.  GCAUTO | enables implicit call of a garbage collector 
  1573.  LONGNAME | use long names in batch files 
  1574.  M2 | forces the Modula-2 compiler 
  1575.  MAIN | marks the Oberon-2 main module 
  1576.  MAKEDEF | generate definition 
  1577.  MAKEFILE | generate makefile 
  1578.  OVERWRITE | create a file, always overwrites the old one 
  1579.  O2 | forces the Oberon-2 compiler 
  1580.  SHOWALIEN | produce warnings on absent modules 
  1581.  VERBOSE | produce verbose messages 
  1582.  WOFF | suppresse warning messages 
  1583.  XCOMMENTS | preserve exported comments 
  1584.  
  1585. Miscellaneous options 
  1586.  
  1587.  
  1588. ΓòÉΓòÉΓòÉ 7.1.1. Description of options ΓòÉΓòÉΓòÉ
  1589.  
  1590. The section lists all options in an alphabetical order. Those options that may 
  1591. be arbitrarily placed in the source code are marked as inline options (See also 
  1592. Source code directives). Some options can be place in the source code, but only 
  1593. before the module header - such options are marked as header. If an option is 
  1594. not marked as a header or inline, then the result of setting it in the source 
  1595. text is undefined. 
  1596.  
  1597. The operation modes to which an option is significant are listed in square 
  1598. brackets ([]) after the option name; the character '*' stands for all operation 
  1599. modes. For example, [browse] means that the option is used by the compiler in 
  1600. the BROWSE operation mode only. Note: in the MAKE and PROJECT mode the compiler 
  1601. switches to the COMPILE mode to compile a module. 
  1602.  
  1603. Run-time check options are ON by default. If it is not explicitly specified, 
  1604. other options are OFF (FALSE) by default. 
  1605.  
  1606.  __GEN_X86__ [compile] 
  1607.  
  1608.            The compiler sets this option ON, if the code generation for 
  1609.            386/486/Pentium is in operation. 
  1610.  
  1611.            The option can be used for compiling different text fragments for 
  1612.            different targets. See also Conditional compilation. 
  1613.  
  1614.  __GEN_C__ [compile] 
  1615.  
  1616.            The compiler sets this option ON, if the C code generation is in 
  1617.            operation. 
  1618.  
  1619.            The option can be used for compiling different text fragments for 
  1620.            different targets. See also Conditional compilation. 
  1621.  
  1622.  ALIGNMENT [compile] 
  1623.  
  1624.            If the option is set OFF, the compiler does not consider any 
  1625.            alignment of data, otherwise it does. See Record types for further 
  1626.            details. 
  1627.  
  1628.            Note: the option cannot be used inline in the source text. 
  1629.  
  1630.  ASSERT    [compile] (inline) 
  1631.  
  1632.            If the option is OFF, the compiler ignores all calls of the standard 
  1633.            ASSERT procedure. 
  1634.  
  1635.            The option is ON by default. 
  1636.  
  1637.  BSCLOSURE [browse] 
  1638.  
  1639.            Include all visible methods. 
  1640.  
  1641.            If the option is set ON, the browser includes all defined and 
  1642.            inherited type-bound procedure declarations with all record 
  1643.            declarations when creating a pseudo-definition module. See also 
  1644.            Creating a definition. 
  1645.  
  1646.  BSREDEFINE [browse] 
  1647.  
  1648.            Include all redefined methods. 
  1649.  
  1650.            If the option is set ON, the browser includes original definitions 
  1651.            of any overwritten type-bound procedures with record declarations. 
  1652.            See also Creating a definition. 
  1653.  
  1654.  CHECKDINDEX [compile] (inline) 
  1655.  
  1656.            A check of dynamic array bounds. 
  1657.  
  1658.            If the option is set ON, the compiler generates index check of 
  1659.            dynamic arrays (POINTER TO ARRAY OF T). 
  1660.  
  1661.            The option is ON by default. 
  1662.  
  1663.  CHECKDIV  [compile] (inline) 
  1664.  
  1665.            If the option is set ON, the compiler generates a check if a divisor 
  1666.            is positive of DIV and MOD operators. 
  1667.  
  1668.            The option is ON by default. 
  1669.  
  1670.  CHECKINDEX [compile] (inline) 
  1671.  
  1672.            A check of static array bounds. 
  1673.  
  1674.            If the option is set ON, the compiler generates index check of all 
  1675.            arrays except dynamic ones (See the CHECKDINDEX option). 
  1676.  
  1677.            The option is ON by default. 
  1678.  
  1679.  CHECKNIL  [compile] (inline) 
  1680.  
  1681.            If the option is set ON, the compiler generates NIL check of all 
  1682.            pointer dereferencies. 
  1683.  
  1684.            The option is ON by default. 
  1685.  
  1686.  CHECKPROC [compile] (inline) 
  1687.  
  1688.            If the option is set ON, the compiler generates NIL check when 
  1689.            calling a procedure variable. 
  1690.  
  1691.            The option is ON by default. 
  1692.  
  1693.  CHECKRANGE [compile] (inline) 
  1694.  
  1695.            If the option is set ON, the compiler generates range checks of 
  1696.            range types and enumerations. 
  1697.  
  1698.            The option is ON by default. 
  1699.  
  1700.  CHECKSET  [compile] (inline) 
  1701.  
  1702.            If the option is set ON, the compiler generates range checks of set 
  1703.            operations (INCL, EXCL, set aggregates). 
  1704.  
  1705.            The option is ON by default. 
  1706.  
  1707.  CHECKTYPE [compile, Oberon-2 only] (inline) 
  1708.  
  1709.            If the option is set ON, the compiler generates dynamic type guards. 
  1710.  
  1711.            The option is ON by default. 
  1712.  
  1713.  COVERFLOW [compile] (inline) 
  1714.  
  1715.            If the option is set ON, the compiler generates overflow checks of 
  1716.            all cardinal (unsigned) arithmetic operators. 
  1717.  
  1718.            The option is ON by default. 
  1719.  
  1720.  DEF       [compile] (header) 
  1721.  
  1722.            Permission to change a module interface (a symbol file). 
  1723.  
  1724.            The Oberon-2 compiler creates a temporary symbol file every time an 
  1725.            Oberon-2 module is compiled, compares this symbol file with the 
  1726.            existing one and overwrites it with the new one if necessary. When 
  1727.            the option is OFF (by default), the compiler reports an error if the 
  1728.            symbol file (and the module interface respectively) had been changed 
  1729.            and does not replace the old symbol file. 
  1730.  
  1731.            Note: if the M2CMPSYM option is set, the same is valid for the 
  1732.            compilation of the Modula-2 definition module, i.e., the DEF option 
  1733.            should be set if the module interface has been changed. 
  1734.  
  1735.  DEFLIBS   [compile] 
  1736.  
  1737.            If the option is set ON, the compiler writes the default library 
  1738.            names to the generated object files. 
  1739.  
  1740.            The option is ON by default. 
  1741.  
  1742.  GCAUTO    [compile,top-level module only] (header) 
  1743.  
  1744.            Enables the implicit call of a garbage collector in the generated 
  1745.            program. The option is ignored for all modules except the top-level 
  1746.            module of the program. We recommend to set the option in the project 
  1747.            or configuration file. 
  1748.  
  1749.  GENDEBUG  [compile] (header) 
  1750.  
  1751.            If the option is set ON, the compiler puts additional debug 
  1752.            information (in OMF format) into an object file. In the current 
  1753.            release (v2.10) this information includes all global variables and 
  1754.            its types. 
  1755.  
  1756.            In some rare cases, switching the option ON may decrease the code 
  1757.            quality. 
  1758.  
  1759.  GENFRAME  [compile] (header) 
  1760.  
  1761.            If the option is set ON, the compiler always generates a stack 
  1762.            frame. It may be necessary to simplify the debugging. 
  1763.  
  1764.  GENHISTORY [compile] (header) 
  1765.  
  1766.            If the option is set ON, the run-time system prints a stack of 
  1767.            procedure calls (a file name and a line number) on abnormal 
  1768.            termination of your program. It should be set when compiling a main 
  1769.            module of the program. In this case the required part of the 
  1770.            run-time system will be added to the program. The option LINENO 
  1771.            should be set for all modules in the program. 
  1772.  
  1773.            In some cases the printed list contains wrong lines, i.e. it 
  1774.            contains procedures that were not called in the given context (See 
  1775.            History). 
  1776.  
  1777.            See also Debugging a program for an example. 
  1778.  
  1779.  GENPTRINIT [compile, Oberon-2 only] (header) 
  1780.  
  1781.            If the option is set ON, the compiler generates code for 
  1782.            initialization all local pointers, including variables, record 
  1783.            fields and array elements. Values of all non-pointer record fields 
  1784.            and array elements are undefined. 
  1785.  
  1786.            The option is ON by default. 
  1787.  
  1788.  IOVERFLOW [compile] (inline) 
  1789.  
  1790.            If the option is set ON, the compiler generates the overflow checks 
  1791.            of all integer (signed) arithmetic operators. 
  1792.  
  1793.            The option is ON by default. 
  1794.  
  1795.  LINENO    [compile] (header) 
  1796.  
  1797.            If the option is set ON, the compiler insert line numbers 
  1798.            information into the object files. This option should be set to get 
  1799.            the postmorten history (See the GENHISTORY option) and for 
  1800.            debugging. 
  1801.  
  1802.  LONGNAME  [make,project] 
  1803.  
  1804.            Use long names. 
  1805.  
  1806.            If the option is set ON, the compiler uses the full path as the 
  1807.            prefix to all module names in the generated batch files. See also 
  1808.            BATCH submode. 
  1809.  
  1810.  M2        [compile] 
  1811.  
  1812.            Force the Modula-2 compiler. 
  1813.  
  1814.            If the option is set ON, XDS invokes the Modula-2 compiler 
  1815.            regardless of file extension. The option is ignored in MAKE and 
  1816.            PROJECT modes. 
  1817.  
  1818.  M2ADDTYPES [compile,Modula-2 only] (header) 
  1819.  
  1820.            Add short and long modifications of whole types. 
  1821.  
  1822.            If the option is set ON, the compiler recognizes the types SHORTINT, 
  1823.            LONGINT, SHORTCARD and LONGCARD as pervasive identifiers . 
  1824.  
  1825.            Warning: A use of additional types may cause problems with the 
  1826.            software portability to other compilers. 
  1827.  
  1828.  M2BASE16  [compile,Modula-2 only] (header) 
  1829.  
  1830.            If the option is set ON, the basic types INTEGER, CARDINAL and 
  1831.            BITSET are 16 bits wide in Modula-2 (by default, 32 bits wide). 
  1832.  
  1833.  M2CMPSYM  [compile,Modula-2 only] 
  1834.  
  1835.            If the option is set ON, the compiler compares the symbol file 
  1836.            generated for a definition module with the old version exactly as 
  1837.            the Oberon-2 compiler does. If the symbol files are equal, the old 
  1838.            one is preserved, otherwise the compiler overwrites symbol file, but 
  1839.            only if the DEF option is set ON. 
  1840.  
  1841.  M2EXTENSIONS [compile,Modula-2 only] (header) 
  1842.  
  1843.            Enable Modula-2 extensions. 
  1844.  
  1845.            If the option is set ON, the compiler allows the Modula-2 language 
  1846.            extensions to be used, such as line comment "-", read-only 
  1847.            parameters, and so on. 
  1848.  
  1849.            Warning: A use of extensions may cause problems with the software 
  1850.            portability to other compilers. 
  1851.  
  1852.  M2UNPACKTYPES [compile,Modula-2 only] (header) 
  1853.  
  1854.            If the option is set ON, the compiler uses 32-bit representation for 
  1855.            Modula-2 enumeration, set and BOOLEAN types. See ??? for further 
  1856.            details. 
  1857.  
  1858.  MAIN      [compile, Oberon-2 only] (header) 
  1859.  
  1860.            Mark the Oberon-2 main module. 
  1861.  
  1862.            If the option is set ON, the compiler generates a program entry 
  1863.            point (`main' function) for the Oberon-2 module (See Program 
  1864.            structure). Inline usage is recommended. 
  1865.  
  1866.  MAKEDEF   [compile,Oberon-2 only] 
  1867.  
  1868.            The MAKEDEF option forces the Oberon compiler to generate a 
  1869.            (pseudo-) definition module after a successful compilation of an 
  1870.            Oberon module. The compiler preserves the so-called exported 
  1871.            comments (i.e. comments started with `(**') if the XCOMMENTS option 
  1872.            is set. 
  1873.  
  1874.            See Creating a definition. 
  1875.  
  1876.  MAKEFILE  [project] 
  1877.  
  1878.            The MAKEFILE option forces XDS to generate a makefile after 
  1879.            successful compilation of a project. See also GEN mode. 
  1880.  
  1881.  NOPTRALIAS [compile] (header) 
  1882.  
  1883.            If the option is set ON, the compiler assumes that there is no 
  1884.            pointer aliasing, i.e. there are no pointers bounded to 
  1885.            non-structure variables. The only way to get a pointer to a variable 
  1886.            is to use the low-level facilities from the module SYSTEM. We 
  1887.            recommend to turn this option ON for all modules except low-level 
  1888.            ones. Note: the code quality is better if the option is ON. 
  1889.  
  1890.  O2        [compile] 
  1891.  
  1892.            Force Oberon-2 compiler. 
  1893.  
  1894.            If the option is set ON, XDS invokes the Oberon-2 compiler 
  1895.            regardless of the file extension. The option is ignored in MAKE and 
  1896.            PROJECT modes. 
  1897.  
  1898.  O2EXTENSIONS [compile,Oberon-2 only] (header) 
  1899.  
  1900.            Enable Oberon-2 extensions. 
  1901.  
  1902.            If the option is set ON, the compiler allows Oberon-2 language 
  1903.            extensions to be used (See Language extensions). 
  1904.  
  1905.            Warning: A use of extensions may cause problems with the software 
  1906.            portability to other compilers. 
  1907.  
  1908.  O2ISOPRAGMA [compile,Oberon-2 only] 
  1909.  
  1910.            If the option is set ON, the compiler allows the ISO M2 style 
  1911.            pragmas <* *> to be used in Oberon-2. See Source code directives and 
  1912.            Source code directives. 
  1913.  
  1914.            Warning: A use of ISO M2 pragmas may cause problems with the 
  1915.            software portability to other compilers. 
  1916.  
  1917.  O2NUMEXT  [compile,Oberon-2 only] (header) 
  1918.  
  1919.            Enable Oberon-2 scientific extensions. 
  1920.  
  1921.            If the option is set ON, the compiler allows the Oberon-2 scientific 
  1922.            language extensions to be used (See Language extensions), including 
  1923.            COMPLEX and LONGCOMPLEX types and the in-line exponentiation 
  1924.            operator. 
  1925.  
  1926.            Warning: A use of additional types may cause problems with the 
  1927.            software portability to other compilers. 
  1928.  
  1929.  OVERWRITE [*] 
  1930.  
  1931.            The option changes the directory where the compiler creates new 
  1932.            files. If the option is OFF, the compiler creates a file in the 
  1933.            directory which appears first in the search path list appropriate to 
  1934.            the filename pattern. Otherwise, the compiler overwrites the old 
  1935.            file. See also Redirection file. 
  1936.  
  1937.  PROCINLINE [compile] 
  1938.  
  1939.            If the option is ON, the compiler tries to expand procedures 
  1940.            in-line. In-line expansion of a procedure saves the overhead usually 
  1941.            associated with procedure calls, parameter passing, register saving, 
  1942.            etc. Sometimes, further optimizations become possible because the 
  1943.            actual parameters used in the call become visible. 
  1944.  
  1945.            A procedure is not expanded in-line under the following 
  1946.            circumstances: 
  1947.  
  1948.                the procedure is deemed too complex or too large by the 
  1949.                 compiler. 
  1950.  
  1951.                there are too many calls of the procedure. 
  1952.  
  1953.                the procedure is recursive. 
  1954.  
  1955.  SHOWALIEN [make,project,gen] 
  1956.  
  1957.            If the option is set ON, the compiler reports a list of all Modula-2 
  1958.            or Oberon-2 modules which are not found within the current project. 
  1959.  
  1960.  SPACE     [compile] 
  1961.  
  1962.            If the option is set ON, the compiler performs optimizations to 
  1963.            produce smaller code, otherwise (by default) to produce faster code. 
  1964.  
  1965.  STORAGE   [compile, Modula-2 only] (header) 
  1966.  
  1967.            If the option is set ON, the compiler uses the default memory 
  1968.            allocation and deallocation procedures for standard procedures NEW 
  1969.            and DISPOSE. 
  1970.  
  1971.            Warning: A use of this option may cause problems with the software 
  1972.            portability to other compilers. 
  1973.  
  1974.  VERBOSE   [make,project] 
  1975.  
  1976.            If the option is set ON, the compiler will report the reason of a 
  1977.            module recompilation (See Smart recompilation). 
  1978.  
  1979.  VERSIONKEY [compile] 
  1980.  
  1981.            The option is introduced to perform version checks at a link time. 
  1982.            If the option is set ON, the compiler generates the name of module 
  1983.            body as composition of 
  1984.  
  1985.                a module name 
  1986.  
  1987.                a string "_BEGIN_" 
  1988.  
  1989.                a time stamp 
  1990.  
  1991.                value of the ALIGNMENT option. 
  1992.  
  1993.            If the definition (or Oberon) module imported by different 
  1994.            compilation units has the same version, the same name is generated 
  1995.            for each call of the module body. In all other cases unresolved 
  1996.            references will occur at link time. 
  1997.  
  1998.            If the option is OFF, the compiler generates the name in the form: 
  1999.            <module_name>_BEGIN. 
  2000.  
  2001.            Note: the option should be set when compiling definition or Oberon 
  2002.            module. 
  2003.  
  2004.  WOFF#     [*] (inline) 
  2005.  
  2006.            When WOFF# (e.g. WOFF301) is ON, the compiler does not report a 
  2007.            warning # (301 in the above example). See xc.msg file for warning 
  2008.            texts and numbers. WOFF without parameter sets all warnings OFF. 
  2009.  
  2010.  XCOMMENTS [compile,Oberon-2 only] 
  2011.  
  2012.            If the option is set ON, the browser includes the so-called exported 
  2013.            comments (i.e. comments which start with `(**') into the generated 
  2014.            pseudo definition module. 
  2015.  
  2016.            See also Creating a definition. 
  2017.  
  2018.  
  2019. ΓòÉΓòÉΓòÉ 7.2. Equations ΓòÉΓòÉΓòÉ
  2020.  
  2021. An equation is a pair (name,value). Equations are used for a change of default 
  2022. file extensions (table ???, page table:equ:ext), code generation settings 
  2023. (table ???, page table:equ:code) and miscellaneous settings (table Description 
  2024. of equations, page table:equ:misc) by the statements of the form: 
  2025.  
  2026.   -NAME=value
  2027.  
  2028. There should be no spaces in an equation statement on the command line. In the 
  2029. configuration or project file, spaces can be placed anywhere, but only one 
  2030. equation per line is allowed (see Options). 
  2031.  
  2032. Equations may be set in the configuration file (See Configuration file), in the 
  2033. project file (See Project files) and on the command line, but not in the source 
  2034. text. At any point of operation, the most recent value of an equation is in 
  2035. effect. All equations are listed in the section Equations. 
  2036.  
  2037. In some cases, the value part of an equation statement may be empty. 
  2038. Examples 
  2039.  
  2040. -mod = .mod
  2041. -DEF = .def
  2042. -mkfext =
  2043.  
  2044.  
  2045. ΓòÉΓòÉΓòÉ 7.2.1. Description of equations ΓòÉΓòÉΓòÉ
  2046.  
  2047. The operation modes to which an equation is significant are enclosed in square 
  2048. brackets ([]) after the option name; the character '*' stands for all operation 
  2049. modes. For example [browse] means that the equation is used by the compiler in 
  2050. the BROWSE operation mode only. Note: the compiler switches from the MAKE and 
  2051. PROJECT mode to the COMPILE mode to compile a module. 
  2052.  
  2053. [htbp] 
  2054.  
  2055. The appearance of the following table is a known problem and will be improved 
  2056. in the final release. 
  2057.  
  2058. |l|c|l| Name | Default | Meaning 
  2059.  BATEXT | .bat | recompilation batch file 
  2060.  BSDEF | .odf | pseudo-definition file created by browser 
  2061.  CODE | .obj| object file 
  2062.  DEF | .def | Modula-2 definition module 
  2063.  MKFEXT | .mkf | makefile 
  2064.  MOD | .mod | Modula-2 implementation or main module 
  2065.  OBERON | .ob2 | Oberon-2 module 
  2066.  OBJEXT | .obj | object file 
  2067.  PRJEXT | .prj | project file 
  2068.  SYM | .sym | symbol file 
  2069.  
  2070. File extensions 
  2071.  
  2072. [htbp] 
  2073.  
  2074. The appearance of the following table is a known problem and will be improved 
  2075. in the final release. 
  2076.  
  2077. |l|c|p6.0cm| Name | Default | Meaning 
  2078.  CC | WATCOM | C compiler compatibility 
  2079.  GCTHRESHOLD | 0 | garbage collector threshold 
  2080.  HEAPLIMIT | 0 | heap limit of a generated program 
  2081.  STACKLIMIT | 0 | stack limit of a generated program 
  2082.  
  2083. Code generator equations 
  2084.  
  2085. [htbp] 
  2086.  
  2087. The appearance of the following table is a known problem and will be improved 
  2088. in the final release. 
  2089.  
  2090. |l|c|p5.0cm| Name | Default | Meaning 
  2091.  ATTENTION | ! | attention character in a template file 
  2092.  BATNAME | out | batch file name 
  2093.  BATWIDTH | 128 | maximum line width in a batch file 
  2094.  BSTYLE | DEF | browse style (See Creating a definition) 
  2095.  COMPILERHEAP | | heap limit of the compiler 
  2096.  COMPILERTHRES | | GC threshold of the compiler 
  2097.  DECOR | hcrt | control of compiler messages 
  2098.  ERRFMT | See Error message format specification | error message format 
  2099.  ERRLIM | 16 | maximum number of errors 
  2100.  LINK | | linker command line 
  2101.  LOOKUP | | lookup directive 
  2102.  MKFNAME | | makefile name 
  2103.  PRJ | | project file name 
  2104.  PROJECT | | project name 
  2105.  TABSTOP | 8 | tabulation alignment 
  2106.  TEMPLATE | | template name (for makefile) 
  2107.  
  2108. Miscellaneous equations 
  2109.  
  2110.  ATTENTION [project,gen] 
  2111.  
  2112.            The equation defines an attention character which is used in the 
  2113.            template file ("!" by default). See Template files. 
  2114.  
  2115.  BATEXT    [batch] 
  2116.  
  2117.            Sets the file extension for recompilation batch files (by default 
  2118.            .bat). See BATCH submode. 
  2119.  
  2120.  BATNAME   [batch] 
  2121.  
  2122.            Sets the batch file name. 
  2123.  
  2124.            The name of the Project file will be used if no batch file name is 
  2125.            explicitly specified. See BATCH submode. 
  2126.  
  2127.  BATWIDTH  [batch] 
  2128.  
  2129.            Sets the maximum width of a line in a generated batch file (by 
  2130.            default 128). See BATCH submode. 
  2131.  
  2132.  BSDEF     [browse] 
  2133.  
  2134.            Sets the file extension for pseudo-definition modules created by the 
  2135.            browser (by default .odf). See BROWSE mode. 
  2136.  
  2137.  BSTYLE    [browse] 
  2138.  
  2139.            Sets the style of generated pseudo-definition modules. See Creating 
  2140.            a definition. 
  2141.  
  2142.  CC        [compile] 
  2143.  
  2144.            Sets the compatibility mode with a C compiler. Currently the 
  2145.            following values are defined: "WATCOM", "MSVC" and "GCC". If the 
  2146.            value of equation is undefined, "WATCOM" is assumed. 
  2147.  
  2148.            The compiler will allow one to use C libraries from the C compiler 
  2149.            specified. 
  2150.  
  2151.            See Chapter Configuring XDS for a C Compiler for more details. 
  2152.  
  2153.  CODE      [*] 
  2154.  
  2155.            Sets the file extension for code files generated by the compiler (by 
  2156.            default .obj). 
  2157.  
  2158.  COMPILERHEAP [*] 
  2159.  
  2160.            Sets the maximum amount of a heap memory (in bytes), that can be 
  2161.            used by the compiler. For the systems with virtual memory, we 
  2162.            recommend to use the value which is less than the amount of the 
  2163.            available memory. 
  2164.  
  2165.  COMPILERTHRES [*] 
  2166.  
  2167.            Sets the garbage collector threshold (in bytes) for the compiler. 
  2168.            The garbage collector will be implicitly called if the amount of a 
  2169.            busy memory exceeds the value of the equation. For the systems with 
  2170.            virtual memory, we recommend to use the value which is less than 
  2171.            COMPILERHEAP. 
  2172.  
  2173.  DECOR     [*] 
  2174.  
  2175.            The equation specifies the output of the xc utility. The value of 
  2176.            equation is a string that contains any combination of letters "h", 
  2177.            "t" "c", "r", "p" (capital letters are also allowed). Each character 
  2178.            turn on an output of 
  2179.  
  2180.            h              header line, which contains a copyright message and 
  2181.                           an utility version 
  2182.  
  2183.            t              the summary of compilation of multiple files 
  2184.  
  2185.            c              the name and version of the compiler's front-end and 
  2186.                           back-end 
  2187.  
  2188.            p              progress messages 
  2189.  
  2190.            r              compiler report: number of errors, lines, etc. 
  2191.  
  2192.            By default, the equation value is "hrtc". 
  2193.  
  2194.  DEF       [*] 
  2195.  
  2196.            Sets the file extension for Modula-2 definition modules (by default 
  2197.            .def). 
  2198.  
  2199.  ERRFMT    [*] 
  2200.  
  2201.            Sets the error message format. See Error message format 
  2202.            specification for details. 
  2203.  
  2204.  ERRLIM    [*] 
  2205.  
  2206.            Sets the maximum number of errors allowed for one compilation unit 
  2207.            (by default 16). 
  2208.  
  2209.  GCTHRESHOLD [compile,top-level module only] 
  2210.  
  2211.            Sets the garbage collector threshold (in bytes). The garbage 
  2212.            collector will be implicitly called if the amount of a busy memory 
  2213.            exceeds the value of the equation. The valid values of the equation 
  2214.            are in the range 0..HEAPLIMIT. We recommend to set the equation for 
  2215.            the systems with virtual memory. 
  2216.  
  2217.  HEAPLIMIT [compile,top-level module only] 
  2218.  
  2219.            Sets the maximum amount of a heap memory, that can be used in the 
  2220.            generated program. The value is set in bytes. 
  2221.  
  2222.            The equation should be set when the top-level module of the program 
  2223.            is compiled. We recommend to set the option in the project or 
  2224.            configuration file. 
  2225.  
  2226.  LINK      [project] 
  2227.  
  2228.            Defines a command line, which will be executed after a successful 
  2229.            completion of a project. As a rule, the equation is used for calling 
  2230.            a linker or make utility. 
  2231.  
  2232.            See Running a program for examples. 
  2233.  
  2234.  LOOKUP    [*] 
  2235.  
  2236.            Sets the lookup directive: 
  2237.  
  2238.                         -LOOKUP = pattern = directory {";" directory }
  2239.  
  2240.            The equation can be used for redefining the search paths that are 
  2241.            set in the redirection file. The configuration or project file or 
  2242.            command line can contain several LOOKUP equations. See also 
  2243.            Configuration file and Project files. 
  2244.  
  2245.  MKFEXT    [gen] 
  2246.  
  2247.            Sets the file extension for a generated makefile (by default .mkf). 
  2248.            See GEN mode. 
  2249.  
  2250.  MKFNAME   [gen] 
  2251.  
  2252.            Sets the name for a generated makefile. See GEN mode. 
  2253.  
  2254.  MOD       [*] 
  2255.  
  2256.            Sets the file extension for the Modula-2 implementation and program 
  2257.            modules (by default .mod). 
  2258.  
  2259.  OBERON    [*] 
  2260.  
  2261.            Sets the file extension for Oberon-2 modules (by default .ob2). 
  2262.  
  2263.  OBJEXT    [*] 
  2264.  
  2265.            Sets the file extension for object files (by default .obj). 
  2266.  
  2267.  PRJ       [compile,make,project] 
  2268.  
  2269.            In the COMPILE and MAKE operation modes, the equation defines a 
  2270.            project file to read settings from. In the PROJECT mode, the 
  2271.            compiler sets this equation to a project file name from the command 
  2272.            line. See PROJECT mode. 
  2273.  
  2274.  PRJEXT    [compile,make,project] 
  2275.  
  2276.            Sets the file extension for a project file (by default .prj). See 
  2277.            PROJECT mode. 
  2278.  
  2279.  PROJECT   [compile,make,project] 
  2280.  
  2281.            If a project file name is defined, the compiler sets the equation to 
  2282.            a project name without a file path and extension. For example, if 
  2283.            the project file name is defined as prj/Work.prj, the value of the 
  2284.            equation is set to Work. The equation may be used in a template file 
  2285.            to set the name of executable file, etc. 
  2286.  
  2287.  STACKLIMIT [compile,top-level module only] 
  2288.  
  2289.            Sets the maximum size of program stack memory. The value is set in 
  2290.            bytes. 
  2291.  
  2292.            The equation should be set when the top-level module of the program 
  2293.            is compiled. We recommend to set the option in the project or 
  2294.            configuration file. 
  2295.  
  2296.            Note: for some linkers the stack size should be set as a linker 
  2297.            option. 
  2298.  
  2299.  SYM       [*] 
  2300.  
  2301.            Sets the file extension for symbol files (by default .sym). See 
  2302.            Files generated during compilation. 
  2303.  
  2304.  TABSTOP   [gen] 
  2305.  
  2306.            When reading text files, XDS replaces TAB character by the number of 
  2307.            spaces required to align a text (by default TABSTOP is equal to 8). 
  2308.            The wrong value may cause misplaced comments in the generated 
  2309.            pseudo-definition module, a wrong location of an error in the error 
  2310.            message, etc. We recommend to set this equation to the number used 
  2311.            in your text editor. 
  2312.  
  2313.  TEMPLATE  [gen] 
  2314.  
  2315.            Sets the name of a template file. See Template files. 
  2316.  
  2317.  
  2318. ΓòÉΓòÉΓòÉ 7.2.2. Error message format specification ΓòÉΓòÉΓòÉ
  2319.  
  2320. The format in which XDS reports the errors is user configurable by using the 
  2321. ERRFMT equation. Its syntax is as follows: 
  2322.  
  2323.   { string "," [ argument ] ";" }.
  2324.  
  2325. Any format specification allowed in the C procedure "printf" can be used in 
  2326. string. 
  2327.  
  2328. The appearance of the following table is a known problem and will be improved 
  2329. in the final release. 
  2330.  
  2331. |l|c|l| Argument |Type |Meaning 
  2332.  line | integer | position in a source text 
  2333.  column | integer | position in a source text 
  2334.  file | string | name of a source file 
  2335.  module | string | module name 
  2336.  errmsg | string | message text 
  2337.  errno | integer | error code 
  2338.  language | string | Oberon-2 or Modula-2 
  2339.  mode | string | ERROR or WARNING or FAULT 
  2340.  utility | string | name of an utility 
  2341.  
  2342. Argument names are not case sensitive. By default the error format includes the 
  2343. following clauses: 
  2344.  
  2345. The appearance of the following table is a known problem and will be improved 
  2346. in the final release. 
  2347.  
  2348. lcl "(%s",file; |-| a file name 
  2349.  "%d",line; |-| a line number 
  2350.  ",%d",column; |-| a column number 
  2351.  ") [%.1s] ",mode; |-| the first letter of an error mode 
  2352.  "%s\n",errmsg; |-| an error message 
  2353.  
  2354. If the warning is reported in the file test.mod on line 5, column 6, the 
  2355. generated error message will look like this: 
  2356.  
  2357. (test.mod 5,6) [W] variable declared but never used
  2358.  
  2359.  
  2360. ΓòÉΓòÉΓòÉ 8. XDS Modula-2 ΓòÉΓòÉΓòÉ
  2361.  
  2362. This chapter includes the details of Modula-2 language which are specific to 
  2363. this implementation. In the standard modeWhen options M2EXTENSIONS and 
  2364. M2ADDTYPES are OFF XDS Modula-2 complies with International Standard (See the 
  2365. statement of compliance and further details in ISO Standard compliance). The 
  2366. compatibility rules are described in Compatibility. The differences between ISO 
  2367. Modula-2 and the language described in the 4th edition of Wirth's ``Programming 
  2368. in Modula-2'' PIM are listed in New language's features. Language extensions 
  2369. are described in Language extensions. 
  2370.  
  2371.  
  2372. ΓòÉΓòÉΓòÉ 8.1. ISO Standard compliance ΓòÉΓòÉΓòÉ
  2373.  
  2374. XDS Modula-2 partially complies with the requirements of ISO 10514. The details 
  2375. of non-conformities are as follows: 
  2376.  
  2377.      Not all libraries are available in the current release. 
  2378.  
  2379.      The current release may impose some restrictions on using new language 
  2380.       features. 
  2381.  
  2382.  See Chapter Implementation limitations and restrictions for further details. 
  2383.  
  2384.  
  2385. ΓòÉΓòÉΓòÉ 8.1.1. Ordering of declarations ΓòÉΓòÉΓòÉ
  2386.  
  2387. XDS Modula-2 is a so-called `single-pass' implementation. It means that all 
  2388. identifiers must be declared before use. According to the International 
  2389. Standard this declare-before-use approach is perfectly valid. The alternative 
  2390. approach (declare-before-use-in-declarations) can be used in the so-called 
  2391. `multi-pass' implementations. 
  2392.  
  2393. A forward declaration must be used to allow forward references to a procedure 
  2394. whose actual declaration appears later in the text. 
  2395. Example 
  2396.  
  2397. PROCEDURE a(x: INTEGER); FORWARD;
  2398. (* FORWARD declaration *)
  2399.  
  2400. PROCEDURE b(x: INTEGER);
  2401. BEGIN
  2402.   a(x-1);
  2403. END b;
  2404.  
  2405. PROCEDURE a(n: INTEGER);
  2406. (* proper procedure declaration *)
  2407. BEGIN
  2408.   b(n-1);
  2409. END a;
  2410.  
  2411. To provide a source compatibility between `single-pass' and `multi-pass' 
  2412. implementation, the standard demands that all conforming `multi-pass' 
  2413. implementations accept and correctly process the FORWARD directive. 
  2414.  
  2415.  
  2416. ΓòÉΓòÉΓòÉ 8.2. New language's features ΓòÉΓòÉΓòÉ
  2417.  
  2418. The language described in the International Standard varies in many details 
  2419. from that one described in Wirth's ``Programming in Modula-2'' PIM. The most 
  2420. important innovations are 
  2421.  
  2422.      complex numbers 
  2423.  
  2424.      module finalization 
  2425.  
  2426.      exception handling 
  2427.  
  2428.      array and record constructors 
  2429.  
  2430.      four new system modules 
  2431.  
  2432.      standard library 
  2433.  
  2434.  Note: The system modules (except the module SYSTEM) are not embedded in the 
  2435.  compiler and are implemented as separate modules. 
  2436.  
  2437.  
  2438. ΓòÉΓòÉΓòÉ 8.2.1. Lexis ΓòÉΓòÉΓòÉ
  2439.  
  2440. The ISO Modula-2 appends new keywords (table ???, page table:m2:ISO:keywords) 
  2441. and pervasive identifiers (table ???, page table:m2:ISO:pervasive), and 
  2442. provides alternatives for some symbols (table Lexis, page table:m2:ISO:alt). It 
  2443. also introduces a syntax for source code directives (or pragmas): 
  2444.  
  2445. pragma = "<*" pragma_body "*>"
  2446.  
  2447. The standard does not specify a syntax of pragma_body. In XDS, source code 
  2448. directives are used for the in-line option control and for the source control 
  2449. (conditional compilation). See Source code directives for further details. 
  2450.  
  2451. [bht] 
  2452.  
  2453. The appearance of the following table is a known problem and will be improved 
  2454. in the final release. 
  2455.  
  2456. p3.4cmp3.4cmp3.4cm AND | ARRAY | BEGIN 
  2457.  BY | CASE | CONST 
  2458.  DEFINITION | DIV | DO 
  2459.  ELSE | ELSIF | END 
  2460.  EXIT | EXCEPT (Exceptions) | EXPORT 
  2461.  FINALLY (Finalization) | FOR | FORWARD (Ordering of declarations) 
  2462.  FROM | IF | IMPLEMENTATION 
  2463.  IMPORT | IN | LOOP 
  2464.  MOD | MODULE | NOT 
  2465.  OF | OR | PACKEDSET (Sets and packedsets) 
  2466.  PROCEDURE | QUALIFIED | RECORD 
  2467.  REM (Whole number division) | RETRY (Exceptions) | REPEAT 
  2468.  RETURN | SET | THEN 
  2469.  TO | TYPE | UNTIL 
  2470.  VAR | WHILE | WITH 
  2471.  
  2472. Modula-2 keywords 
  2473.  
  2474. [hbtp] 
  2475.  
  2476. The appearance of the following table is a known problem and will be improved 
  2477. in the final release. 
  2478.  
  2479. p5.0cmp5.0cm ABS | BITSET 
  2480.  BOOLEAN | CARDINAL 
  2481.  CAP | CHR 
  2482.  CHAR | COMPLEX (Complex types) 
  2483.  CMPLX (Complex types) | DEC 
  2484.  DISPOSE | EXCL 
  2485.  FALSE | FLOAT 
  2486.  HALT | HIGH 
  2487.  IM (Complex types) | INC 
  2488.  INCL | INT (Type conversions) 
  2489.  INTERRUPTIBLE (Protection) | INTEGER 
  2490.  LENGTH (Strings) | LFLOAT (Type conversions) 
  2491.  LONGCOMPLEX (Complex types) | LONGREAL 
  2492.  MAX | MIN 
  2493.  NEW | NIL 
  2494.  ODD | ORD 
  2495.  PROC | PROTECTION (Protection) 
  2496.  RE (Complex types) | REAL 
  2497.  SIZE | TRUE 
  2498.  TRUNC | UNINTERRUPTIBLE (Protection) 
  2499.  VAL 
  2500.  
  2501. Modula-2 pervasive identifiers 
  2502.  
  2503. [htbp] 
  2504.  
  2505. The appearance of the following table is a known problem and will be improved 
  2506. in the final release. 
  2507.  
  2508. |c|l|c| Symbol | Meaning | Alternative 
  2509.  [ | left bracket | (! 
  2510.  ] | right bracket | !) 
  2511.  { | left brace | (: 
  2512.  } | right brace | :) 
  2513.  | | case separator | ! 
  2514.  ^ | dereference | @ 
  2515.  
  2516. Modula-2 alternative symbols 
  2517.  
  2518.  
  2519. ΓòÉΓòÉΓòÉ 8.2.2. Complex types ΓòÉΓòÉΓòÉ
  2520.  
  2521. Types COMPLEX and LONGCOMPLEX can be used to represent complex numbers. These 
  2522. types differ in a the range and precision. The COMPLEX type is defined as a 
  2523. (REAL,REAL) pair, while LONGCOMPLEX consists of a pair of LONGREAL values. 
  2524.  
  2525. There is no notation for a complex literal. A complex value can be obtained by 
  2526. applying the standard function CMPLX to two reals. If both CMPLX arguments are 
  2527. real constants the result is the complex constant. 
  2528.  
  2529. CONST i = CMPLX(0.0,1.0);
  2530.  
  2531. If both expressions are of the REAL type, or if one is of the REAL type and the 
  2532. other is a real constant, the function returns the COMPLEX value. If both 
  2533. expressions are of the LONGREAL type, or if one is of the LONGREAL type and the 
  2534. other is a real constant the function returns the LONGCOMPLEX value. The 
  2535. following table summarizes the permitted types and the result type: 
  2536.  
  2537. The appearance of the following table is a known problem and will be improved 
  2538. in the final release. 
  2539.  
  2540. |l|lll|| REAL | LONGREAL | real constant 
  2541.  REAL | REAL | error| COMPLEX 
  2542.  LONGREAL | error| LONGCOMPLEX | LONGCOMPLEX 
  2543.  real constant | COMPLEX | LONGCOMPLEX | complex constant 
  2544.  
  2545. Standard functions RE and IM can be used to obtain a real or imaginary part of 
  2546. a value of a complex type. Both functions have one parameter. If the parameter 
  2547. is of the COMPLEX type, both functions return a REAL value; if the parameter is 
  2548. of the LONGCOMPLEX type, functions return a LONGREAL value; otherwise the 
  2549. parameter should be a complex constant and functions return a real constant. 
  2550.  
  2551. CONST one = IM(CMPLX(0.0,1.0));
  2552.  
  2553. There are four arithmetic operations for operands of a complex type: addition 
  2554. (+), subtraction (-), multiplication (*) and division (/). The following table 
  2555. indicates the result of an operation for the combinations permitted: 
  2556.  
  2557. The appearance of the following table is a known problem and will be improved 
  2558. in the final release. 
  2559.  
  2560. |l|lll|| COMPLEX | LONGCOMPLEX | complex constant 
  2561.  COMPLEX | COMPLEX | error| COMPLEX 
  2562.  LONGCOMPLEX | error| LONGCOMPLEX | LONGCOMPLEX 
  2563.  complex constant | COMPLEX | LONGCOMPLEX | complex constant 
  2564.  
  2565. There are two arithmetic monadic operations that can be applied to the values 
  2566. of a complex type: identity (+) and negation (-). The result of an operation is 
  2567. of the operand's type. 
  2568.  
  2569. Two complex comparison operators are provided for operands of complex type: 
  2570. equality and inequality. 
  2571. Example 
  2572.  
  2573. PROCEDURE abs(z: COMPLEX): REAL;
  2574. BEGIN
  2575.   RETURN RealMath.sqrt(RE(z)*RE(z)+IM(z)*IM(z))
  2576. END abs;
  2577.  
  2578.  
  2579. ΓòÉΓòÉΓòÉ 8.2.3. Sets and packedsets ΓòÉΓòÉΓòÉ
  2580.  
  2581. A set and packedset Packedset types are innovated in the standard. type defines 
  2582. a new type, whose set of values is the power set of an associated ordinal type 
  2583. called the base type of a set type. 
  2584.  
  2585. SetType       = SET OF Type;
  2586. PackedsetType = PACKEDSET OF Type;
  2587.  
  2588. The International Standard does not require a specific representation for set 
  2589. types. Packedset types have a representation that is mapped to the individual 
  2590. bits of a particular underlying architecture. The standard type BITSET is a 
  2591. pre-defined packedset type. 
  2592.  
  2593. The current XDS implementation does not distinguish between the set and 
  2594. packedset types. A set of at least 256 elements can be defined. 
  2595. Example 
  2596.  
  2597. TYPE
  2598.   CharSet = SET OF CHAR;
  2599.   LongSet = PACKEDSET OF [-127..128];
  2600.  
  2601. All set operations, such as union (+), difference (-), intersection (*), and 
  2602. symmetrical difference (/) can be applied to the values of both set and 
  2603. packedset types. 
  2604. Example 
  2605.  
  2606.    VAR letters, digits, alphanum: CharSet;
  2607.    ...
  2608.    letters  := CharSet{'a'..'z','A'..'Z'};
  2609.    digits   := CharSet{'0'..'9'};
  2610.    alphanum := letters + digits;
  2611.  
  2612.  
  2613. ΓòÉΓòÉΓòÉ 8.2.4. Strings ΓòÉΓòÉΓòÉ
  2614.  
  2615. For operands of the string literal type the string concatenation operation is 
  2616. defined, denoted by the symbol "+". Note: a character number literal (e.g. 15C) 
  2617. denotes a value of a literal string type of length 1. The empty string is 
  2618. compatible with the type CHAR and has a value equal to the string terminator 
  2619. (0C). 
  2620. Example 
  2621.  
  2622. CONST
  2623.   CR = 15C;
  2624.   LF = 12C;
  2625.   LineEnd = CR + LF;
  2626.   Greeting = "hello " + "world" + LineEnd;
  2627.  
  2628. The new standard function LENGTH can be used to obtain the length of a string 
  2629. value. 
  2630.  
  2631. PROCEDURE LENGTH(s: ARRAY OF CHAR): CARDINAL;
  2632.  
  2633.  
  2634. ΓòÉΓòÉΓòÉ 8.2.5. Value constructors ΓòÉΓòÉΓòÉ
  2635.  
  2636. A value constructor is an expression denoting a value of an array type, a 
  2637. record type, or a set type. In case of array constructors and record 
  2638. constructors a list of values, known as structure components, is specified to 
  2639. define the values of components of an array value or the fields of a record 
  2640. value. In case of a set constructor, a list of members is specified, whose 
  2641. elements define the elements of the set values. 
  2642.  
  2643. ValueConstructor = ArrayValue
  2644.                  | RecordValue
  2645.                  | SetValue.
  2646. ArrayValue = TypeIdentifier "{"
  2647.              ArrayComponent { "," ArrayComponent }
  2648.              "}".
  2649. ArrayComponent = Component [ BY RepeatCount ].
  2650. Component   = Expression.
  2651. RepeatCount = ConstExpression.
  2652. RecordValue = TypeIdentifier "{"
  2653.              Component { "," Component }
  2654.              "}".
  2655.  
  2656. Set constructors are described in PIM. 
  2657.  
  2658. The total number of components of an array constructor must be exactly the same 
  2659. as the number of array's elements (taking into account any repetition of 
  2660. components). Each component must be an assignment compatible with the array 
  2661. base type. 
  2662.  
  2663. The number of components of a record constructor must be exactly the same as 
  2664. the number of fields. Each component must be an assignment compatible with the 
  2665. type of the field. 
  2666.  
  2667. A special case is a record constructor for a record with variant parts. If the 
  2668. n-th field is the tag field the n-th component must be a constant expression. 
  2669. If there is no ELSE variant part associated with the tag field, then a variant 
  2670. associated with the value of expression should exist. If no variant is 
  2671. associated with the value, then the fields of the ELSE variant part should be 
  2672. included in the sequence of components. 
  2673.  
  2674. The constructor's components may themselves contain lists of elements, and such 
  2675. nested constructs need not specify a type identifier. This relaxation is 
  2676. necessary for multi-dimensional arrays, where the types of the inner components 
  2677. may be anonymous. 
  2678. Examples 
  2679.  
  2680. TYPE
  2681.   String = ARRAY [0..15] OF CHAR;
  2682.   Person = RECORD
  2683.     name: String;
  2684.     age : CARDINAL;
  2685.   END;
  2686.   Vector = ARRAY [0..2] OF INTEGER;
  2687.   Matrix = ARRAY [0..2] OF Vector;
  2688.  
  2689. VAR
  2690.   string: String;
  2691.   person: Person;
  2692.   vector: Vector;
  2693.   matrix: Matrix;
  2694. ....
  2695.   string:=String{" " BY 16};
  2696.   person:=Person{"Alex",32};
  2697.   vector:=Vector{1,2,3};
  2698.   matrix:=Matrix{vector,{4,5,6},Vector{7,8,9}};
  2699.   matrix:=Matrix{vector BY 3};
  2700.  
  2701.  
  2702. ΓòÉΓòÉΓòÉ 8.2.6. Multi-dimensional open arrays ΓòÉΓòÉΓòÉ
  2703.  
  2704. According to the International Standard, the parameters of a multi-dimensional 
  2705. open array are allowed. 
  2706. Example 
  2707.  
  2708. PROCEDURE Foo(VAR matrix: ARRAY OF ARRAY OF REAL);
  2709.   VAR i,j: CARDINAL;
  2710. BEGIN
  2711.   FOR i:=0 TO HIGH(matrix)
  2712.     FOR j:=0 TO HIGH(matrix[i])
  2713.       ... matrix[i,j] ...
  2714.     END;
  2715.   END;
  2716. END Foo;
  2717.  
  2718. VAR a: ARRAY [0..2],[0..2] OF REAL;
  2719.  
  2720. BEGIN
  2721.   Foo(a);
  2722. END ...
  2723.  
  2724.  
  2725. ΓòÉΓòÉΓòÉ 8.2.7. Procedure type declarations ΓòÉΓòÉΓòÉ
  2726.  
  2727. A procedure type identifier may be used in declaring of the type itself. This 
  2728. feature is used in the Standard Library. See, for example, modules ConvTypes 
  2729. and WholeConv. 
  2730. Example 
  2731.  
  2732. TYPE
  2733.   Scan = PROCEDURE (CHAR; VAR Scan);
  2734.   Func = PROCEDURE (INTEGER): Func;
  2735.  
  2736.  
  2737. ΓòÉΓòÉΓòÉ 8.2.8. Procedure constants ΓòÉΓòÉΓòÉ
  2738.  
  2739. A constant expression may contain the values of procedure types, or structured 
  2740. values whose components are the values of procedure types. Procedure constants 
  2741. may be used as a mechanism for procedure renaming. In a definition module it is 
  2742. possible to export a renamed version of imported procedure. 
  2743. Examples 
  2744.  
  2745. TYPE ProcTable = ARRAY [0..3] OF PROC;
  2746.  
  2747. CONST
  2748.   WS = STextIO.WriteString;
  2749.   Table = ProcTable{Up,Down,Left,Right};
  2750.  
  2751.  
  2752. ΓòÉΓòÉΓòÉ 8.2.9. Whole number division ΓòÉΓòÉΓòÉ
  2753.  
  2754. Along with DIV and MOD the International Standard includes two additional 
  2755. operators for whole number division: `/' and REM. 
  2756.  
  2757. Operators DIV and MOD are defined for positive divisors only, while `/' and REM 
  2758. can be used for both negative and positive divisors. 
  2759.  
  2760. The language exception wholeDivException (See Exceptions) is raised if: 
  2761.  
  2762.      second operand is zero (for all four operators) 
  2763.  
  2764.      second operand of DIV or MOD is negative. 
  2765.  
  2766.  For the given lval and rval 
  2767.  
  2768.     quotient  := lval / rval;
  2769.     remainder := lval REM rval;
  2770.  
  2771.  the following is true (for all non-zero values of rval): 
  2772.  
  2773.     
  2774.  
  2775.             lval = rval * quotient + remainder
  2776.  
  2777.      a value of remainder is either zero, or an integer of the same sign as 
  2778.       lval and of a smaller absolute value than rval. 
  2779.  
  2780.  For the given lval and rval 
  2781.  
  2782.     quotient := lval DIV rval;
  2783.     modulus  := lval MOD rval;
  2784.  
  2785.  the following is true (for all positive values of rval): 
  2786.  
  2787.     
  2788.  
  2789.             lval = rval * quotient + modules
  2790.  
  2791.      a value of modulus is a non-negative integer less than rval. 
  2792.  
  2793.  Operations are exemplified in the following table: 
  2794.  
  2795.  The appearance of the following table is a known problem and will be improved 
  2796.  in the final release. 
  2797.  
  2798.  |c|c|c|c|c| op | 31 op 10 | 31 op (-10) | (-31) op 10 | (-31) op (-10) 
  2799.   / | 3 | -3 | -3 | 3 
  2800.   REM | 1 | 1 | -1 | -1 
  2801.   DIV | 3 | exception | -4 | exception 
  2802.   MOD | 1 | exception | 9 | exception 
  2803.  
  2804.  
  2805. ΓòÉΓòÉΓòÉ 8.2.10. Type conversions ΓòÉΓòÉΓòÉ
  2806.  
  2807. The language includes the following type conversion functions: CHR, FLOAT, INT, 
  2808. LFLOAT, ORD, TRUNC and VAL. The functions INT and LFLOAT are not described in 
  2809. PIM. 
  2810.  
  2811. All the type conversion functions (except VAL) have a single parameter and can 
  2812. be expressed in terms of the VAL function. 
  2813.  
  2814. The appearance of the following table is a known problem and will be improved 
  2815. in the final release. 
  2816.  
  2817. |l|l|l|l| Name | Parameter | Result | Equal to 
  2818.  CHR | whole | CHAR | VAL(CHAR,x) 
  2819.  FLOAT | real or whole | REAL | VAL(REAL,x) 
  2820.  INT | real or ordinal | INTEGER | VAL(INTEGER,x) 
  2821.  LFLOAT | real or whole | LONGREAL | VAL(LONGREAL,x) 
  2822.  ORD | ordinal | CARDINAL | VAL(CARDINAL,x) 
  2823.  TRUNC | real | CARDINAL | VAL(CARDINAL,x) 
  2824.  
  2825. The function VAL can be used to obtain a value of a specified scalar type from 
  2826. an expression of a scalar type. The function has two parameters. The first 
  2827. parameter should be a type parameter that denotes a scalar type. If the type is 
  2828. a subrange type, the call of VAL returns the host type of the subrange type, 
  2829. otherwise it returns the type denoted by the type parameter. 
  2830.  
  2831. The second parameter should be an expression of a scalar type and at least one 
  2832. of the restriction shall hold: 
  2833.  
  2834.      the result type and the type of the expression are identical 
  2835.  
  2836.      both the result type and the type of the expression are whole or real 
  2837.  
  2838.      the result type or the type of the expression is a whole type 
  2839.  
  2840.  In the following table, ΓêÜ denotes a valid combination of types and ┬╖ denotes 
  2841.  an invalid combination: 
  2842.  
  2843.  The appearance of the following table is a known problem and will be improved 
  2844.  in the final release. 
  2845.  
  2846.  |lccccc| the type of | 5cthe type denoted by the type parameter 
  2847.   expression | whole | real | CHAR |BOOLEAN | enumeration 
  2848.   whole type | ΓêÜ | ΓêÜ | ΓêÜ | ΓêÜ | ΓêÜ 
  2849.   real type | ΓêÜ | ΓêÜ | ┬╖ | ┬╖ | ┬╖ 
  2850.   CHAR | ΓêÜ | ┬╖ | ΓêÜ | ┬╖ | ┬╖ 
  2851.   BOOLEAN | ΓêÜ | ┬╖ | ┬╖ | ΓêÜ | ┬╖ 
  2852.   enumeration | ΓêÜ | ┬╖ | ┬╖ | ┬╖ | ΓêÜ 
  2853.  
  2854.  An exception is raised if the value x lies outside the range of type T in the 
  2855.  call VAL(T,x). If x is of a real type, the calls VAL(INTEGER,x) and 
  2856.  VAL(CARDINAL,x) both truncates the value of x. 
  2857.  
  2858.  
  2859. ΓòÉΓòÉΓòÉ 8.2.11. NEW and DISPOSE ΓòÉΓòÉΓòÉ
  2860.  
  2861. The standard NEW and DISPOSE procedures are back in the language. Calls of NEW 
  2862. and DISPOSE are substituted by calls of ALLOCATE and DEALLOCATE which should be 
  2863. visible in the current scope. The compiler checks the compliance of these 
  2864. substitution procedures with the expected formal type: 
  2865.  
  2866. PROCEDURE ALLOCATE(VAR a: ADDRESS; size: CARDINAL);
  2867. PROCEDURE DEALLOCATE(VAR a: ADDRESS; size: CARDINAL);
  2868.  
  2869. As a rule, the procedures ALLOCATE and DEALLOCATE declared in the module 
  2870. Storage are used. These procedures are made visible by including the import 
  2871. list: 
  2872.  
  2873. FROM Storage IMPORT ALLOCATE, DEALLOCATE;
  2874.  
  2875. When the language extensions are enabled the procedures NEW and DISPOSE can be 
  2876. applied to dynamic arrays. See NEW and DISPOSE for dynamic arrays for further 
  2877. details. 
  2878.  
  2879.  
  2880. ΓòÉΓòÉΓòÉ 8.2.12. Finalization ΓòÉΓòÉΓòÉ
  2881.  
  2882. A special mechanism called finalization is provided to perform certain 
  2883. operation during program termination. 
  2884.  
  2885. A module declaration contains an optional finalization body, which is executed 
  2886. during program termination for static modules (See Termination) or dynamic 
  2887. module finalization. 
  2888.  
  2889. ModuleBody = [ BEGIN BlockBody
  2890.              [ FINALLY BlockBody ] ] END
  2891. BlockBody  = NormalPart
  2892.              [ EXCEPT ExceptionalPart ].
  2893. NormalPart = StatementSequence.
  2894. ExceptionalPart = StatementSequence.
  2895.  
  2896. Note: a RETURN statement can be used in a BlockBody. 
  2897. Example 
  2898.  
  2899. MODULE Test;
  2900.  
  2901. ....
  2902.  
  2903. VAR cid: StreamFile.ChanId;
  2904.  
  2905. BEGIN
  2906.   StreamFile.Open(cid,"tmp",flags,res);
  2907.   Process(cid);
  2908. FINALLY
  2909.   StreamFile.Close(cid);
  2910. END Test
  2911.  
  2912. If the Test module is declared in a procedure block, then the initialization 
  2913. body will be executed on a call of the procedure, while the finalization body 
  2914. is executed after the procedure body. 
  2915.  
  2916. If the Test module is a static module, its finalization will be executed during 
  2917. the program termination. 
  2918.  
  2919. In any case the finalization bodies are executed in inverse order to their 
  2920. initializations. 
  2921.  
  2922. In the following example, a finalization of a local module is used to provide a 
  2923. correct context restoration: 
  2924.  
  2925. VAR state: State;
  2926.  
  2927. PROCEDURE Foo;
  2928.  
  2929.   MODULE AutoSave;
  2930.     IMPORT state, State;
  2931.     VAR save: State;
  2932.   BEGIN
  2933.     save:=state; (* save state *)
  2934.     state:=fooState;
  2935.   FINALLY
  2936.     state:=save; (* restore state *)
  2937.   END AutoSave;
  2938.  
  2939. BEGIN
  2940.   ... process ...
  2941. END Foo;
  2942.  
  2943. The initialization part of the AutoSave module will be executed before any 
  2944. statement in the Foo body and finalization part will be executed directly 
  2945. before ending of the call of Foo. 
  2946.  
  2947.  
  2948. ΓòÉΓòÉΓòÉ 8.2.13. Exceptions ΓòÉΓòÉΓòÉ
  2949.  
  2950. An exception handling mechanism is now included in the language. Both 
  2951. user-defined exceptions and language exceptions can be handled. There is no 
  2952. special exception type, exceptions are identified by the pair: exception source 
  2953. value and cardinal value. Two keywords (EXCEPT and RETRY) are added to the 
  2954. language. The essential part of exception handling is provided in two system 
  2955. modules: EXCEPTIONS and M2EXCEPTION. 
  2956.  
  2957. The EXCEPTIONS module provides facilities for raising and identifying the 
  2958. user-defined exceptions, for reporting their occurrence, and for making 
  2959. enquiries concerning the execution state of the current coroutine. 
  2960.  
  2961. The M2EXCEPTION module provides facilities for identifying language exceptions 
  2962. that have been raised. 
  2963.  
  2964. A procedure body, the initialization or finalization part of module body may 
  2965. contain an exceptional part. 
  2966.  
  2967. BlockBody  = NormalPart [ EXCEPT ExceptionalPart ].
  2968. NormalPart = StatementSequence.
  2969. ExceptionalPart = StatementSequence.
  2970.  
  2971. Example 
  2972.  
  2973. PROCEDURE Div(a,b: INTEGER): INTEGER;
  2974. BEGIN
  2975.   RETURN a DIV b      (* try to divide *)
  2976. EXCEPT
  2977.   RETURN MAX(INTEGER) (* if exception *)
  2978. END Fly;
  2979.  
  2980. When an exception is raised (explicitly or implicitly) the `nearest' (in terms 
  2981. of procedure calls) exceptional part in the current coroutine gets the control. 
  2982. Each coroutine is executed initially in a normal state. If an exception is 
  2983. raised, the coroutine state switches to an exceptional state. If there is no 
  2984. exceptional part, the raising of exception is a termination event (See 
  2985. Termination). 
  2986.  
  2987. A procedure with an exceptional part is executed in the normal state. The state 
  2988. is restored after the block execution. A procedure without an exceptional part 
  2989. is executed in the state of the caller. 
  2990.  
  2991. If an exception is raised in the state of exceptional execution it is re-raised 
  2992. in the calling context. In this case finalization of local modules and 
  2993. restoring protection (See Protection) will not take place. 
  2994.  
  2995. An additional statement (RETRY) can be used in the exceptional part. Execution 
  2996. of the RETRY statement causes the normal part to be re-executed in the normal 
  2997. state. 
  2998.  
  2999. Execution of the RETURN statement in the exceptional part causes switch to the 
  3000. normal state. 
  3001.  
  3002. If neither RETURN nor RETRY was executed in the exceptional part, the 
  3003. exceptional completion will occur. In this case after finalization of local 
  3004. modules (if any) and restoring protection state (if necessary), the exception 
  3005. will be re-raised. 
  3006. Example 
  3007.  
  3008. PROCEDURE Foo;
  3009. BEGIN
  3010.   TryFoo(...);
  3011. EXCEPT
  3012.   IF CanBeRepaired() THEN
  3013.     Repair;
  3014.     RETRY;  (* re-execute the normal part *)
  3015.   ELSIF CanBeProcessed() THEN
  3016.     Process;
  3017.     RETURN; (* exception is handled *)
  3018.   ELSE
  3019.     (* exception will be automatically re-raised *)
  3020.   END;
  3021. END Foo;
  3022.  
  3023.  
  3024. ΓòÉΓòÉΓòÉ 8.2.14. The system module EXCEPTIONS ΓòÉΓòÉΓòÉ
  3025.  
  3026. The module EXCEPTIONS provides facilities for raising user's exceptions and for 
  3027. making enquiries concerning the current execution state. 
  3028.  
  3029. User-defined exceptions are identified uniquely by a pair (exception source, 
  3030. number). When the source of a used-defined exception is a separate module, it 
  3031. prevents the defined exceptions of the module from being raised directly by 
  3032. other sources. See e.g. the module Storage. 
  3033.  
  3034. TYPE ExceptionSource;
  3035.  
  3036. Values of the opaque type ExceptionSource are used to identify the source of 
  3037. exceptions raised; they should be allocated before usage. 
  3038.  
  3039. TYPE ExceptionNumber = CARDINAL;
  3040.  
  3041. Values of the type ExceptionNumber are used to distinguish between different 
  3042. exceptions of one source. 
  3043.  
  3044. PROCEDURE AllocateSource(VAR newSource: ExceptionSource);
  3045.  
  3046. The procedure allocates an unique value of the type ExceptionSource. The 
  3047. procedure is normally called during initialization of the module, and the 
  3048. resulting value is then used in all calls of RAISE. If an unique value cannot 
  3049. be allocated the language exception exException is raised (See The system 
  3050. module M2EXCEPTION). 
  3051.  
  3052. PROCEDURE RAISE(source: ExceptionSource;
  3053.                 number: ExceptionNumber;
  3054.                message: ARRAY OF CHAR);
  3055.  
  3056. The procedure call associates the given values of a source, number and message 
  3057. with the current context and raises an exception. 
  3058.  
  3059. The function CurrentNumber can be used to obtain the exception number for the 
  3060. current exception. 
  3061.  
  3062. PROCEDURE CurrentNumber
  3063.    (source: ExceptionSource): ExceptionNumber;
  3064.  
  3065. If the calling coroutine is in the exceptional execution state because of 
  3066. raising an exception from source, the procedure returns the corresponding 
  3067. number, and otherwise raises an exception. 
  3068.  
  3069. The procedure GetMessage can be used to obtain the message passed when an 
  3070. exception is raised. This may give further information about the nature of the 
  3071. exception. 
  3072.  
  3073. PROCEDURE GetMessage(VAR text: ARRAY OF CHAR);
  3074.  
  3075. If the calling coroutine is in the exceptional execution state, the procedure 
  3076. returns the possibly truncated string associated with the current context. 
  3077. Otherwise, in a normal execution state, it returns the empty string. 
  3078.  
  3079. PROCEDURE IsCurrentSource
  3080.         (source: ExceptionSource): BOOLEAN;
  3081.  
  3082. If the current coroutine is in the exceptional execution state because of 
  3083. raising an exception from source, the procedure returns TRUE, and FALSE 
  3084. otherwise. 
  3085.  
  3086. PROCEDURE IsExceptionalExecution (): BOOLEAN;
  3087.  
  3088. If the current coroutine is in the exceptional execution state because of 
  3089. raising an exception, the procedure returns TRUE, and FALSE otherwise. 
  3090.  
  3091. The following example illustrates the recommended form of a library module and 
  3092. the usage of procedures from EXCEPTIONS. 
  3093.  
  3094. DEFINITION MODULE FooLib;
  3095.  
  3096. PROCEDURE Foo;
  3097. (* Raises Foo exception if necessary *)
  3098.  
  3099. PROCEDURE IsFooException(): BOOLEAN;
  3100. (* Returns TRUE, if the calling coroutine is in
  3101.    exceptional state because of the raising of
  3102.    an exception from Foo, and otherwise returns FALSE.
  3103. *)
  3104.  
  3105. END FooLib.
  3106.  
  3107. IMPLEMENTATION MODULE FooLib;
  3108.  
  3109. IMPORT EXCEPTIONS;
  3110.  
  3111. VAR source: EXCEPTIONS.ExceptionSource;
  3112.  
  3113. PROCEDURE Foo;
  3114. BEGIN
  3115.   TryFoo(...);
  3116.   IF NOT done THEN
  3117.     EXCEPTIONS.RAISE(source,0,"Foo exception");
  3118.   END;
  3119. END Foo;
  3120.  
  3121. PROCEDURE IsFooException(): BOOLEAN;
  3122. BEGIN
  3123.   RETURN EXCEPTIONS.IsCurrentSource(source)
  3124. END IsLibException;
  3125.  
  3126. BEGIN
  3127.   EXCEPTIONS.AllocateSource(source)
  3128. END FooLib.
  3129.  
  3130. If we want to distinguish the exceptions raised in the FooLib we will append an 
  3131. enumeration type and an additional enquiry procedure in the FooLib definition: 
  3132.  
  3133. TYPE FooExceptions = (fault, problem);
  3134.  
  3135. PROCEDURE FooException(): FooExceptions;
  3136.  
  3137. The FooException procedure can be implemented as follows: 
  3138.  
  3139. PROCEDURE FooException(): FooExceptions;
  3140. BEGIN
  3141.   RETURN VAL(FooExceptions,
  3142.              EXCEPTIONS.CurrentNumber(source))
  3143. END FooException;
  3144.  
  3145. The Client module illustrates the usage of a library module: 
  3146.  
  3147. MODULE Client;
  3148.  
  3149. IMPORT  FooLib, EXCEPTIONS, STextIO;
  3150.  
  3151. PROCEDURE ReportException;
  3152.   VAR s: ARRAY [0..63] OF CHAR;
  3153. BEGIN
  3154.   EXCEPTIONS.GetMessage(s);
  3155.   STextIO.WriteString(s);
  3156.   STextIO.WriteLn;
  3157. END ReportException;
  3158.  
  3159. PROCEDURE TryFoo;
  3160. BEGIN
  3161.   FooLib.Foo;
  3162. EXCEPT
  3163.   IF FooLib.IsFooException() THEN
  3164.     ReportException;
  3165.     RETURN; (* exception is handled *)
  3166.   ELSE
  3167.     (* Exception will be re-raised *)
  3168.   END
  3169. END TryFoo;
  3170.  
  3171. END Client.
  3172.  
  3173.  
  3174. ΓòÉΓòÉΓòÉ 8.2.15. The system module M2EXCEPTION ΓòÉΓòÉΓòÉ
  3175.  
  3176. The system module M2EXCEPTION provides facilities for identifying language 
  3177. exceptions. The language (which includes the system modules) is regarded as one 
  3178. source of exceptions. 
  3179.  
  3180. The module provides the enumeration type in terms of which the language 
  3181. exceptions are raised and two enquiry functions. 
  3182.  
  3183. TYPE
  3184.   M2Exceptions =
  3185.     (indexException,      rangeException,
  3186.      caseSelectException, invalidLocation,
  3187.      functionException,   wholeValueException,
  3188.      wholeDivException,   realValueException,
  3189.      realDivException,    complexValueException,
  3190.      complexDivException, protException,
  3191.      sysException,        coException,
  3192.      exException
  3193.     );
  3194.  
  3195. PROCEDURE IsM2Exception(): BOOLEAN;
  3196.  
  3197. If the current coroutine is in the exceptional execution state because of 
  3198. raising a language exception, the procedure returns TRUE, and FALSE otherwise. 
  3199.  
  3200. PROCEDURE M2Exception(): M2Exceptions;
  3201.  
  3202. If the current coroutine is in the exceptional execution state because of 
  3203. raising a language exception, the procedure returns the corresponding 
  3204. enumeration value, and otherwise raises an exception. 
  3205.  
  3206. The following description lists all language exceptions (in an alphabetical 
  3207. order) along with the circumstances in which exceptions are detected. Note: 
  3208. Compiler options can be used to control the detection of some exceptions (See 
  3209. Chapter Compiler Options and Equations). Detection of some exceptions is not 
  3210. required, however such exceptions can be detected on some platforms (See 
  3211. Chapter Implementation limitations and restrictions). 
  3212.  
  3213.  caseSelectException 
  3214.  
  3215.            Case selector is out of range and the ELSE clause does not exist. 
  3216.  
  3217.  coException 
  3218.  
  3219.            The system module COROUTINES exceptions: 
  3220.  
  3221.                RETURN from coroutine other than the main coroutine 
  3222.  
  3223.                size of the supplied workspace smaller than the minimum 
  3224.                 required (See NEWCOROUTINE) 
  3225.  
  3226.                the caller is not attached to the source of interrupts (See 
  3227.                 HANDLER) 
  3228.  
  3229.                coroutine workspace overflow 
  3230.  
  3231.  complexDivException 
  3232.  
  3233.            Divide by zero in a COMPLEX expression. 
  3234.  
  3235.  complexValueException 
  3236.  
  3237.            Overflow in evaluation of a COMPLEX expression. 
  3238.  
  3239.  exException 
  3240.  
  3241.            The system modules EXCEPTIONS and M2EXCEPTION exception: 
  3242.  
  3243.                exception identity is enquiry in normal execution (See 
  3244.                 CurrentNumber) 
  3245.  
  3246.                exception identity enquiry to a wrong source (SeeCurrentNumber) 
  3247.  
  3248.                no further exception source values can be allocated (See 
  3249.                 AllocateSource) 
  3250.  
  3251.  functionException 
  3252.  
  3253.            No RETURN statement before the end of a function. 
  3254.  
  3255.  indexException 
  3256.  
  3257.            Array indexed out of range. See options CHECKINDEX and CHECKDINDEX. 
  3258.  
  3259.  invalidLocation 
  3260.  
  3261.            Attempt to dereference NIL or uninitialized pointer. See the option 
  3262.            CHECKNIL. 
  3263.  
  3264.  protException 
  3265.  
  3266.            Given protection is less restrictive than the current protection. 
  3267.  
  3268.  rangeException 
  3269.  
  3270.            Range exception (See the CHECKRANGE option): 
  3271.  
  3272.                assignment value is out of range of a target 
  3273.  
  3274.                structure component value is out of range 
  3275.  
  3276.                expression cannot be converted to a new type 
  3277.  
  3278.                value to be included/excluded is not of the base type of a set 
  3279.                 (See also the CHECKSET option) 
  3280.  
  3281.                return value is out of range 
  3282.  
  3283.                set value is out of range (See also the CHECKSET option) 
  3284.  
  3285.                tag value is out of range (in a variant record). 
  3286.  
  3287.  realDivException 
  3288.  
  3289.            Divide by zero in a REAL expression. 
  3290.  
  3291.  realValueException 
  3292.  
  3293.            Overflow in evaluation of a REAL expression. 
  3294.  
  3295.  sysException 
  3296.  
  3297.            The system module SYSTEM exceptions. Note: All these exceptions are 
  3298.            non-mandatory. 
  3299.  
  3300.                invalid use of ADDADR, SUBADR or DIFADR 
  3301.  
  3302.                the result of MAKEADR is out of the address range 
  3303.  
  3304.                alignment problem with CAST 
  3305.  
  3306.                the result of CAST is not a valid representation for the target 
  3307.                 type 
  3308.  
  3309.  wholeDivException 
  3310.  
  3311.            Whole division exception: 
  3312.  
  3313.                divided by zero in evaluation of a whole number expression 
  3314.  
  3315.                the second operand of DIV or MOD is negative (See the CHECKDIV 
  3316.                 option) 
  3317.  
  3318.  wholeValueException 
  3319.  
  3320.            Overflow in evaluation of a whole number expression. 
  3321.  
  3322.  Example of handling a language exception 
  3323.  
  3324.   PROCEDURE Div(a,b: INTEGER): INTEGER;
  3325.   BEGIN
  3326.     RETURN a DIV b
  3327.   EXCEPT
  3328.     IF IsM2Exception() THEN
  3329.       IF M2Exception() = wholeDivException THEN
  3330.         IF a < 0 THEN RETURN MIN(INTEGER)
  3331.         ELSE          RETURN MAX(INTEGER)
  3332.         END;
  3333.       END;
  3334.     END;
  3335.   END Div;
  3336.  
  3337.  
  3338. ΓòÉΓòÉΓòÉ 8.2.16. Termination ΓòÉΓòÉΓòÉ
  3339.  
  3340. During the program termination, finalization of those static modules that have 
  3341. started initialization are executed in inverse order their initialization (See 
  3342. also Finalization). The static modules are the program module, the 
  3343. implementation modules, and any local modules declared in the module blocks of 
  3344. these modules. 
  3345.  
  3346. Program termination starts from the first occurrence of the following event: 
  3347.  
  3348.    1. the end of the program module body is reached 
  3349.  
  3350.    2. a RETURN statement is executed in the program module body 
  3351.  
  3352.    3. the standard procedure HALT is called 
  3353.  
  3354.    4. an exception is raised and this exception is not handled. 
  3355.  
  3356.  The system module TERMINATION provides facilities for enquiries concerning the 
  3357.  occurrence of termination events. 
  3358.  
  3359.   PROCEDURE IsTerminating(): BOOLEAN;
  3360.  
  3361.  Returns TRUE if any coroutine has started the program termination and FALSE 
  3362.  otherwise. 
  3363.  
  3364.   PROCEDURE HasHalted(): BOOLEAN;
  3365.  
  3366.  Returns TRUE if a call of HALT has been made and FALSE otherwise. 
  3367.  
  3368.  
  3369. ΓòÉΓòÉΓòÉ 8.2.17. Coroutines ΓòÉΓòÉΓòÉ
  3370.  
  3371. The system module COROUTINES provides facilities for creating coroutines, for 
  3372. the explicit transfer of control between coroutines, and for handling of the 
  3373. interrupts. Note: Some features can be unavailable in the current release. See 
  3374. Chapter Implementation limitations and restrictions for details. 
  3375.  
  3376. Values of the type COROUTINE are created dynamically by a call of NEWCOROUTINE 
  3377. and identify the coroutine in subsequent operations. A particular coroutine is 
  3378. identified by the same value of the coroutine type throughout the lifetime of 
  3379. that coroutine. 
  3380.  
  3381. TYPE COROUTINE;
  3382.  
  3383. The correspondent type was called PROCESS in PIM. From the third edition of 
  3384. PIM, the ADDRESS type was used to identify a coroutine. 
  3385.  
  3386. PROCEDURE NEWCOROUTINE(
  3387.                 procBody: PROC;
  3388.                 workspace: SYSTEM.ADDRESS;
  3389.                 size: CARDINAL;
  3390.                 VAR cr: COROUTINE
  3391.                 [; initProtection: PROTECTION]);
  3392.  
  3393. Creates a new coroutine whose body is given by procBody, and returns the 
  3394. identity of the coroutine in cr. workspace is a pointer to the work space 
  3395. allocated to the coroutine; size specifies the size of this workspace in terms 
  3396. of SYSTEM.LOC. initProtection is an optional parameter that specifies the 
  3397. initial protection level of the coroutine. 
  3398.  
  3399. An exception is raised (See coException) if the value of size is less than the 
  3400. minimum workspace size. 
  3401.  
  3402. If the optional parameter is omitted, the initial protection of the coroutine 
  3403. is given by the current protection of the caller. 
  3404.  
  3405. The created coroutine is initialized in such a way that when control is first 
  3406. transferred to that coroutine, the procedure given by procBody is called in a 
  3407. normal state. The exception (coException) is raised when the procBody procedure 
  3408. attempts to return to its caller. Since the caller has no exception handler, 
  3409. raising this exception is a termination event. 
  3410.  
  3411. The procedure TRANSFER can be used to transfer control from one coroutine to 
  3412. another. 
  3413.  
  3414. PROCEDURE TRANSFER (VAR from: COROUTINE; to: COROUTINE);
  3415.  
  3416. Returns the identity of the calling coroutine in from and transfers control to 
  3417. the coroutine specified by to. 
  3418.  
  3419. PROCEDURE CURRENT (): COROUTINE;
  3420.  
  3421. Returns the identity of the calling coroutine. 
  3422. Interrupt handling 
  3423.  
  3424. The INTERRUPTSOURCE type is used to identify interrupts. 
  3425.  
  3426. TYPE INTERRUPTSOURCE = INTEGER;
  3427.  
  3428. Programs that use the interrupt handling facilities may be non-portable since 
  3429. the type is implementation-defined. 
  3430.  
  3431. PROCEDURE ATTACH(source: INTERRUPTSOURCE);
  3432.  
  3433. Associates the specified source of interrupts with the calling coroutine. More 
  3434. than one source of interrupts may be associated with a single coroutine. 
  3435.  
  3436. PROCEDURE DETACH(source: INTERRUPTSOURCE);
  3437.  
  3438. Dissociates the specified source of interrupts from the calling coroutine. The 
  3439. call has no effect if the coroutine is not associated with source. 
  3440.  
  3441. PROCEDURE IsATTACHED(source: INTERRUPTSOURCE): BOOLEAN;
  3442.  
  3443. Returns TRUE if and only if the specified source of interrupts is currently 
  3444. associated with a coroutine; otherwise returns FALSE. 
  3445.  
  3446. PROCEDURE HANDLER(source: INTERRUPTSOURCE): COROUTINE;
  3447.  
  3448. Returns the coroutine, if any, that is associated with the source of 
  3449. interrupts. The result is undefined if there is no coroutine associated with 
  3450. the source. 
  3451.  
  3452. PROCEDURE IOTRANSFER(VAR from: COROUTINE;
  3453.                            to: COROUTINE);
  3454.  
  3455. Returns the identity of the calling coroutine in from and transfers control to 
  3456. the coroutine specified by to. On occurrence of an interrupt, associated with 
  3457. the caller, control is transferred back to the caller, and from returns the 
  3458. identity of the interrupted coroutine. An exception is raised if the calling 
  3459. coroutine is not associated with a source of interrupts. 
  3460. Protection 
  3461.  
  3462. See section Protection for information about PROTECTION type. 
  3463.  
  3464. PROCEDURE LISTEN(prot: PROTECTION);
  3465.  
  3466. Momentarily changes protection of the calling coroutine to prot, usually 
  3467. lowering it so as to allow an interrupt request to be granted. 
  3468.  
  3469. PROCEDURE PROT(): PROTECTION;
  3470.  
  3471. Returns protection of the calling coroutine. 
  3472.  
  3473.  
  3474. ΓòÉΓòÉΓòÉ 8.2.18. Protection ΓòÉΓòÉΓòÉ
  3475.  
  3476. A program module, implementation module or local module may specify, by 
  3477. including protection in its heading, that execution of the enclosed statement 
  3478. sequence is protected. 
  3479.  
  3480. ModuleHeading = MODULE ident [ Protection ] ";".
  3481. Protection    = [ ConstExpression ].
  3482.  
  3483. A module with protection in its heading is called a directly protected module. 
  3484. A directly protected procedure is an exported procedure declared in the 
  3485. protected module. 
  3486.  
  3487. Protection of a module is provided by surrounding the externally accessible 
  3488. procedures and module body by calls of access control procedures. The value of 
  3489. the protection expression is passed to the call of access control procedures as 
  3490. an actual parameter. 
  3491.  
  3492. The protection expression should be of the PROTECTION type. The PROTECTION type 
  3493. is an elementary type with at least two values: INTERRUPTIBLE and 
  3494. UNINTERRUPTIBLE. 
  3495.  
  3496. Operators <, >, <= and >= can be used to compare the values of the PROTECTION 
  3497. type. If x is a value of PROTECTION type, then x satisfies the conditions: 
  3498.  
  3499.  UNINTERRUPTIBLE ?x? INTERRUPTIBLE 
  3500.  
  3501.  
  3502. ΓòÉΓòÉΓòÉ 8.3. Standard procedures ΓòÉΓòÉΓòÉ
  3503.  
  3504. [hbt] 
  3505.  
  3506. The appearance of the following table is a known problem and will be improved 
  3507. in the final release. 
  3508.  
  3509. |cl|p6.5cm| |Procedure |Meaning 
  3510.  ΓêÜ | ASSERT(x[,n]) | Terminates program if x?TRUE (See ASSERT) 
  3511.  ΓêÜ 
  3512.  
  3513.  | COPY(x,v) | Copy string: v := x (See Proper procedures) 
  3514.  |DEC(v[,n]) | v := v - n, default n=1 
  3515.  |DISPOSE(v) | Deallocates v'136(See NEW and DISPOSE) 
  3516.  |EXCL(v,n) | v := v - {n} 
  3517.  |HALT | Terminates program execution (See HALT) 
  3518.  |INC(v[,n]) | v := v + n, default n=1 
  3519.  |INCL(v,n) | v := v + {n} 
  3520.  |NEW(v) | Allocates v'136(See NEW and DISPOSE) 
  3521.  ΓêÜ | NEW(v,x0xn) | Allocates v'136of length x0xn (See NEW and DISPOSE for 
  3522. dynamic arrays and Pointer types) 
  3523.  
  3524. Modula-2 proper procedures 
  3525.  
  3526. [htb] 
  3527.  
  3528. The appearance of the following table is a known problem and will be improved 
  3529. in the final release. 
  3530.  
  3531. |cl|p7.5cm| |Function |Meaning 
  3532.  |ABS(x) | Absolute value of x 
  3533.  ΓêÜ|ASH(x,n) | Arithmetic shift 
  3534.  |CAP(x) | Corresponding capital letter 
  3535.  |CHR(x) | Character with an ordinal number x 
  3536.  |CMPLX(x,y) | Complex number with real part x and imaginary part y 
  3537.  ΓêÜ|ENTIER(x) | Largest integer not greater than x 
  3538.  |FLOAT(x) |VAL(REAL,x) 
  3539.  |HIGH(v) | High bound of the index of v 
  3540.  |IM(x) | Imaginary part of a complex x 
  3541.  |INT(x) |VAL(INTEGER,x) 
  3542.  ΓêÜ|LEN(v[,n]) | Length of an array in the dimension n (default=0) 
  3543.  |LENGTH(x) | String length 
  3544.  |LFLOAT(x) |VAL(LONGREAL,x) 
  3545.  |MAX(T) | Maximum value of type T 
  3546.  |MIN(T) | Minimum value of type T 
  3547.  |ODD(x) | x MOD 2 = 1 
  3548.  |ORD(x) |VAL(CARDINAL,x) 
  3549.  |RE(x) | Real part of a complex x 
  3550.  |SIZE(T) | The number of storage units, required by a variable of type T 
  3551.  |TRUNC(x) | Truncation to the integral part 
  3552.  |VAL(T,x) | Type conversion 
  3553.  
  3554. Modula-2 function procedures 
  3555.  
  3556. This section is intended for a brief description of the set of standard 
  3557. procedures and functions. Some of the procedures and functions are not 
  3558. described in the International Standard and are available only if the option 
  3559. M2EXTENSIONS is set. The procedure HALT may have an additional parameter, if 
  3560. the extensions are enabled (See HALT). 
  3561.  
  3562. In the tables (??? and Standard procedures) of predefined procedures, v means a 
  3563. designator, x, y and n mean an expression, T means a type. Non-standard 
  3564. procedures are marked with ΓêÜ. 
  3565.  
  3566. The procedure COPY and the functions ASH, ENTIER and LEN are described in the 
  3567. Oberon report (See Predeclared procedures). 
  3568.  
  3569.  
  3570. ΓòÉΓòÉΓòÉ 8.4. Compatibility ΓòÉΓòÉΓòÉ
  3571.  
  3572. This section describes compatibility between entities of different types. There 
  3573. are three forms of compatibility: 
  3574.  
  3575.      expression compatibility (specifying the types that may be combined in 
  3576.       expressions); 
  3577.  
  3578.      assignment compatibility (specifying the type of a value that may be 
  3579.       assigned to a variable); 
  3580.  
  3581.      parameter compatibility (specifying the type of an actual parameter that 
  3582.       may be passed to a formal parameter). 
  3583.  
  3584.  The rules for parameter compatibility are relaxed in the case where a formal 
  3585.  parameter is of a system storage type. This variation is known as the system 
  3586.  parameter compatibility. 
  3587.  
  3588.  In most cases the compatibility rules are the same as described in PIM. 
  3589.  However, we suppose to explicitly list all the rules. 
  3590.  
  3591.  
  3592. ΓòÉΓòÉΓòÉ 8.4.1. Expression compatibility ΓòÉΓòÉΓòÉ
  3593.  
  3594. Two expressions a and b of types Ta and Tb are expression compatible if any of 
  3595. the following statement is true: 
  3596.  
  3597.    1. The types Ta and Tb are identical. Note: If a type is a subrange type, 
  3598.       then only its host type matters, therefore values of subranges of the 
  3599.       same host type are expression compatible with each other and with the 
  3600.       host type. 
  3601.  
  3602.    2. A type of one expression is a complex type, and the other expression is a 
  3603.       complex constant. 
  3604.  
  3605.    3. A type of one expression is a real type, and the other expression is a 
  3606.       real constant. 
  3607.  
  3608.    4. A type of one expression is a whole type, and the other expression is a 
  3609.       whole constant. 
  3610.  
  3611.    5. A type of one expression is character, and the other expression is a 
  3612.       string literal of length 0 or 1. See also Strings. 
  3613.  
  3614.             VAR
  3615.               char: CHAR;
  3616.               ...
  3617.               WHILE (char # '') & (char # ".") DO
  3618.               ...
  3619.  
  3620.  
  3621. ΓòÉΓòÉΓòÉ 8.4.2. Assignment compatibility ΓòÉΓòÉΓòÉ
  3622.  
  3623. An expression e of type Te is assignment compatible with the variable v of type 
  3624. Tv if one of the following conditions holds For an expression of a subrange 
  3625. type only host type matters. : 
  3626.  
  3627.    1. Tv is identical to the type Te, and the type is not an open array type. 
  3628.  
  3629.    2. Tv is a subrange of the type Te. 
  3630.  
  3631.    3. Tv is the CARDINAL type or a subrange of the CARDINAL type and Te is the 
  3632.       INTEGER type or e is a whole constant. 
  3633.  
  3634.    4. Tv is the INTEGER type or a subrange of the INTEGER type and Te is the 
  3635.       CARDINAL type or e is a whole constant. 
  3636.  
  3637.    5. Tv is a real type and e is a real constant. 
  3638.  
  3639.    6. Tv is a complex type and e is a complex constant. 
  3640.  
  3641.    7. Tv is a pointer type and e is NIL. 
  3642.  
  3643.    8. Tv is a procedure type and e is the designator of a procedure which has 
  3644.       the same structure as the procedure type Tv and which has been declared 
  3645.       at level 0. 
  3646.  
  3647.    9. Tv is the character type or a subrange of the character type and e is a 
  3648.       string literal of length 0 or 1. 
  3649.  
  3650.   10. Tv is an array type having the character type as its component type, and 
  3651.       e is a string literal of length less then or equal to the number of 
  3652.       components in arrays of type TvA string literal is not assignment 
  3653.       compatible with an array whose component's type is a subrange of the 
  3654.       character type.. 
  3655.  
  3656.   11. Tv is the address type and Te is a pointer type or Te is the address type 
  3657.       and Tv is a pointer type. 
  3658.  
  3659.  
  3660. ΓòÉΓòÉΓòÉ 8.4.3. Value parameter compatibility ΓòÉΓòÉΓòÉ
  3661.  
  3662. A formal type is value parameter compatible with an actual expression if any of 
  3663. the following statements is true: 
  3664.  
  3665.    1. The formal type is constructed from a system storage type and is system 
  3666.       parameter compatible with the expression. 
  3667.  
  3668.    2. The formal parameter is an open array, the actual parameter is an array 
  3669.       type and the component type of the formal type is value parameter 
  3670.       compatible with the component type of the actual type A formal array 
  3671.       parameter with the component's type T is not parameter compatible with 
  3672.       the actual parameter of type T.. 
  3673.  
  3674.    3. The formal type is assignment compatible with the actual parameter. 
  3675.  
  3676.  
  3677. ΓòÉΓòÉΓòÉ 8.4.4. Variable parameter compatibility ΓòÉΓòÉΓòÉ
  3678.  
  3679. A formal type is variable parameter compatible with an actual variable if any 
  3680. of the following statements is true: 
  3681.  
  3682.    1. The formal type is constructed from a system storage type and is system 
  3683.       parameter compatible with the expression. 
  3684.  
  3685.    2. The formal parameter is an open array, the actual parameter is an array 
  3686.       type and the component's type of the formal type is variable parameter 
  3687.       compatible with the component's type of the actual parameter type. 
  3688.  
  3689.    3. The formal type is identical to the actual parameter type. 
  3690.  
  3691.  
  3692. ΓòÉΓòÉΓòÉ 8.4.5. System parameter compatibility ΓòÉΓòÉΓòÉ
  3693.  
  3694. A formal type is system parameter compatible with an actual parameter if any of 
  3695. the following statements is true: 
  3696.  
  3697.    1. The formal parameter is of the SYSTEM.LOC type and the actual parameter 
  3698.       is of any type T such that SIZE(T) is equal to 1. 
  3699.  
  3700.    2. The formal parameter is of the type 
  3701.  
  3702.             ARRAY [0..n-1] OF SYSTEM.LOC
  3703.  
  3704.       and the actual parameter is of any type T such that SIZE(T) is equal to 
  3705.       n. 
  3706.  
  3707.    3. The formal parameter is of the open array type 
  3708.  
  3709.             ARRAY OF SYSTEM.LOC
  3710.  
  3711.       and the actual parameter is of any type but not numeric literal. 
  3712.  
  3713.    4. The formal parameter is of the multi-dimensional open array type 
  3714.  
  3715.             ARRAY OF ARRAY [0..n-1] OF SYSTEM.LOC
  3716.  
  3717.       and the actual parameter is of any type T such that SIZE(T) is a multiple 
  3718.       of n. 
  3719.  
  3720.  
  3721. ΓòÉΓòÉΓòÉ 8.5. The module SYSTEM ΓòÉΓòÉΓòÉ
  3722.  
  3723. The module SYSTEM provides the low-level facilities for gaining an access to 
  3724. the address and underlying storage of variables, performing address arithmetic 
  3725. operations and manipulating the representation of values. Program that use 
  3726. these facilities may be non-portable. 
  3727.  
  3728. This module does not exist in the same sense as other libraries but is 
  3729. hard-coded into the compiler itself. To use the facilities provided, however, 
  3730. identifiers must be imported in a usual way. 
  3731.  
  3732. Some of the SYSTEM module procedures are generic procedures that cannot be 
  3733. explicitly declared, i.e. they apply to classes of operand types or have 
  3734. several possible forms of a parameter list . 
  3735.  
  3736. The SYSTEM module is the only module specified in the International Standard 
  3737. that can be extended in the implementation. The XDS SYSTEM module provides 
  3738. additional types and procedures. 
  3739.  
  3740. DEFINITION MODULE SYSTEM;
  3741.  
  3742. CONST
  3743.   BITSPERLOC  = 8;
  3744.   LOCSPERWORD = 4;
  3745.   LOCSPERBYTE = 1;
  3746.  
  3747. TYPE
  3748.   LOC;
  3749.   ADDRESS = POINTER TO LOC;
  3750.   WORD = ARRAY [0 .. LOCSPERWORD-1] OF LOC;
  3751.   BYTE = LOC;
  3752.  
  3753. PROCEDURE ADDADR(addr: ADDRESS; offset: CARDINAL): ADDRESS;
  3754. PROCEDURE SUBADR(addr: ADDRESS; offset: CARDINAL): ADDRESS;
  3755. PROCEDURE DIFADR(addr1, addr2: ADDRESS): INTEGER;
  3756.  
  3757. PROCEDURE MAKEADR(val: <whole type>): ADDRESS;
  3758.  
  3759. PROCEDURE ADR(VAR v: <anytype>): ADDRESS;
  3760.  
  3761. PROCEDURE ROTATE(val: <a packedset type>;
  3762.                  num: INTEGER): <type of the first parameter>;
  3763.  
  3764. PROCEDURE SHIFT(val: <a packedset type>;
  3765.                 num: INTEGER): <type of the first parameter>;
  3766.  
  3767. PROCEDURE CAST(<targettype>;
  3768.                val: <anytype>): <targettype>;
  3769.  
  3770. PROCEDURE TSIZE (<type>; ... ): CARDINAL;
  3771.  
  3772. (*------------------------------------------------------- *)
  3773. (* -------------- non-standard features ----------------- *)
  3774.  
  3775. TYPE
  3776.   INT8   = <integer 8-bits type>;
  3777.   INT16  = <integer 16-bits type>;
  3778.   INT32  = <integer 32-bits type>;
  3779.   CARD8  = <cardinal 8-bits type>;
  3780.   CARD16 = <cardinal 16-bits type>;
  3781.   CARD32 = <cardinal 32-bits type>;
  3782.   BOOL8  = <boolean 8-bits type>;
  3783.   BOOL32 = <boolean 32-bits type>;
  3784.   INDEX  = <type of index>
  3785.   DIFADR_TYPE = <type that DIFADR function returns>
  3786.  
  3787. TYPE (* for use in Oberon *)
  3788.   INT  = <Modula-2 INTEGER type>;
  3789.   CARD = <Modula-2 CARDINAL type>;
  3790.  
  3791. TYPE (* for interfacing to C *)
  3792.   int      = <C int type>;
  3793.   unsigned = <C unsigned type>;
  3794.   size_t   = <C size_t type>;
  3795.   void     = <C void type>;
  3796.  
  3797. PROCEDURE MOVE(src,dest: ADDRESS; size: CARDINAL);
  3798.  
  3799. PROCEDURE GET(adr: ADDRESS; VAR var: SimpleType);
  3800. PROCEDURE PUT(adr: ADDRESS; var: SimpleType);
  3801.  
  3802. PROCEDURE CC(n: CARDINAL): BOOLEAN;
  3803.  
  3804. END SYSTEM.
  3805.  
  3806.  
  3807. ΓòÉΓòÉΓòÉ 8.5.1. System types ΓòÉΓòÉΓòÉ
  3808.  
  3809.  LOC 
  3810.  
  3811.            Values of the LOC type are the uninterpreted contents of the 
  3812.            smallest addressable unit of a storage in implementation. The value 
  3813.            of the call TSIZE(LOC) is therefore equal to one. 
  3814.  
  3815.            The type LOC was introduced as a mechanism to resolve the problems 
  3816.            with BYTE and WORD types. Its introduction allows a consistent 
  3817.            handling of both these types, and enables also WORD-like types to be 
  3818.            further introduced, eg: 
  3819.  
  3820.                       TYPE WORD16 = ARRAY [0..1] OF SYSTEM.LOC;
  3821.  
  3822.            The only operation directly defined for the LOC type is an 
  3823.            assignment. There are special rules affecting parameter 
  3824.            compatibility for system storage types. See System parameter 
  3825.            compatibility for further details. 
  3826.  
  3827.  BYTE 
  3828.  
  3829.            BYTE is defined as LOC and has all the properties of the type LOC. 
  3830.  
  3831.  WORD 
  3832.  
  3833.            The type WORD is defined as 
  3834.  
  3835.                       CONST LOCSPERWORD = 4;
  3836.                       TYPE WORD = ARRAY [0..LOCSPERWORD-1] OF LOC;
  3837.  
  3838.            and the value of the call TSIZE(WORD) is equal to LOCSPERWORD. 
  3839.  
  3840.            The only operation directly defined for the WORD type is an 
  3841.            assignment. There are special rules affecting parameter 
  3842.            compatibility for system storage types. See System parameter 
  3843.            compatibility for further details. 
  3844.  
  3845.  ADDRESS 
  3846.  
  3847.            The type ADDRESS is defined as 
  3848.  
  3849.                         TYPE ADDRESS = POINTER TO LOC;
  3850.  
  3851.            The ADDRESS type is an assignment compatible with all pointer types 
  3852.            and vice versa (See Assignment compatibility). A formal variable 
  3853.            parameter of the ADDRESS type is a parameter compatible with an 
  3854.            actual parameter of any pointer type. 
  3855.  
  3856.            Variables of type ADDRESS are no longer expression compatible with 
  3857.            CARDINAL (as was in PIM) and they cannot directly occur in 
  3858.            expressions that include arithmetic operators. Functions ADDADR, 
  3859.            SUBADR and DIFADR were introduced for address arithmetic. 
  3860.  
  3861.  Whole system types 
  3862.  
  3863.            Types INT8, CARD8, INT16, CARD16, INT32, CARD32 are guaranteed to 
  3864.            contain 8, 16, or 32 bits respectively. 
  3865.  
  3866.            These types are introduced to simplify constructing the interfaces 
  3867.            for foreign libraries (See Chapter Multilanguage programming). Types 
  3868.            SHORTINT, LONGINT, SHORTCARD, LONGCARD are synonyms of INT8, INT32, 
  3869.            CARD8, CARD32, respectively (See also the M2ADDTYPES option). Types 
  3870.            INTEGER and CARDINAL are synonyms of INT16/INT32, CARD16/CARD32, 
  3871.            depending on the platform. 
  3872.  
  3873.            These types are not described in the International Standard. 
  3874.  
  3875.  Boolean system types 
  3876.  
  3877.            Types BOOL8 and BOOL32 are guaranteed to contain 8 and 32 bits 
  3878.            respectively. By default the compiler uses BOOL8 type for BOOLEAN. 
  3879.            In some cases (e.g. in interface to OS/2 or Windows API) BOOL32 
  3880.            should be used instead (See also the option M2UNPACKTYPES). 
  3881.  
  3882.  Modula-2 whole types 
  3883.  
  3884.            Types INT and CARD are equal to Modula-2 INTEGER and CARDINAL types, 
  3885.            respectively. These types can be used in Oberon-2 in order to use 
  3886.            Modula-2 procedures in portable way. See Modula-2 and Oberon-2 for 
  3887.            further details. 
  3888.  
  3889.  Interface to C 
  3890.  
  3891.            Types int, unsigned, size_t and void are introduced to simplify 
  3892.            constructing the interfaces to C libraries. See Interfacing to C for 
  3893.            further details. 
  3894.  
  3895.  
  3896. ΓòÉΓòÉΓòÉ 8.5.2. System functions ΓòÉΓòÉΓòÉ
  3897.  
  3898. PROCEDURE ADDADR(addr: ADDRESS;
  3899.                  offs: CARDINAL): ADDRESS;
  3900.  
  3901. Returns an address given by (addr + offs). The subsequent use of the calculated 
  3902. address may raise an exception. 
  3903.  
  3904. PROCEDURE SUBADR(addr: ADDRESS;
  3905.                  offs: CARDINAL): ADDRESS;
  3906.  
  3907. Returns an address given by (addr - offs). The subsequent use of the calculated 
  3908. address may raise an exception. 
  3909.  
  3910. PROCEDURE DIFADR(addr1,addr2: ADDRESS): INTEGER;
  3911.  
  3912. Returns the difference between addresses (addr1 - addr2). 
  3913.  
  3914. PROCEDURE MAKEADR(val: <whole type>): ADDRESS;
  3915.  
  3916. The function is used to construct a value of the ADDRESS type from the value of 
  3917. a whole typeThe International Standard does not define the number and types of 
  3918. the parameters. Programs that use this procedure may be non-portable.. 
  3919.  
  3920. PROCEDURE ADR(VAR v: <any type>): ADDRESS;
  3921.  
  3922. Returns the address of the variable v. 
  3923.  
  3924. PROCEDURE CAST(<type>; x: <any type>): <type>;
  3925.  
  3926. The function CAST can be used (as a type transfer function) to interpret a 
  3927. value of any type other than a numeric literal value as a value of another type 
  3928. The International Standard forbids the use of the PIM style type transfer, like 
  3929. CARDINAL(x).. 
  3930.  
  3931. The value of the call CAST(Type,val) is an unchecked conversion of val to the 
  3932. type Type. If SIZE(val) = TSIZE(Type), the bit pattern representation of the 
  3933. result is the same as the bit pattern representation of val; otherwise the 
  3934. result and the value of val have the same bit pattern representation for a size 
  3935. equal to the smaller of the numbers of storage units. 
  3936.  
  3937. The given implementation may forbid some combinations of parameter types. 
  3938.  
  3939. PROCEDURE TSIZE(Type; ... ): CARDINAL;
  3940.  
  3941. Returns the number of storage units (LOCS) used to store the value of the 
  3942. specified type. The extra parameters, if present, are used to distinguish 
  3943. variants in a variant record and must be constant expressionsThose constant 
  3944. expressions are ignored in the current release.. 
  3945. Example 
  3946.  
  3947. TYPE
  3948.   R = RECORD
  3949.     CASE i: INTEGER OF
  3950.       |1: r: REAL;
  3951.       |2: b: BOOLEAN;
  3952.     END;
  3953.   END;
  3954.  
  3955.   ... TSIZE(R,1) ...
  3956.  
  3957. The value of TSIZE(T) is equal to SIZE(T). 
  3958. Packedset functions 
  3959.  
  3960. Values of PACKEDSET types are represented as sequences of bits The current 
  3961. implementation does not distinguish between set and packedset types.. The bit 
  3962. number 0 is the least significant bit for a given platform. The following is 
  3963. true, where v is a variable of the type CARDINAL: 
  3964.  
  3965.         CAST(CARDINAL,BITSET{0}) = VAL(CARDINAL,1)
  3966.         SHIFT(CAST(BITSET,v),1)  = v * 2
  3967.         SHIFT(CAST(BITSET,v),-1) = v DIV 2
  3968.  
  3969. The functions ROTATE and SHIFT can be applied to a set with size less than or 
  3970. equal to the size of BITSET. 
  3971.  
  3972. PROCEDURE ROTATE(x: T; n: integer): T;
  3973.  
  3974. Returns the value of x rotated n bits to the left (for positive n) or to the 
  3975. right (for negative n). 
  3976.  
  3977. PROCEDURE SHIFT(x: T; n: integer): T;
  3978.  
  3979. Returns the value of x logically shifted n bits to the left (for positive n) or 
  3980. to the right (for negative n). 
  3981. Non-standard functions 
  3982.  
  3983. PROCEDURE CC(n: whole constant): BOOLEAN;
  3984.  
  3985. Returns TRUE if the corresponding condition flag is set. The function is not 
  3986. implemented in the current release. 
  3987.  
  3988. PROCEDURE BIT(adr: T; bit: INTEGER): BOOLEAN;
  3989.  
  3990. Returns bit n of Mem[adr]. T is either ADDRESS or whole type. 
  3991.  
  3992.  
  3993. ΓòÉΓòÉΓòÉ 8.5.3. System procedures ΓòÉΓòÉΓòÉ
  3994.  
  3995. Note: all these procedures are non-standard. 
  3996.  
  3997. PROCEDURE MOVE (src, dst: ADDRESS; size: CARDINAL);
  3998.  
  3999. Copies size bytes from a memory location specified by src to a memory location 
  4000. specified by dst. 
  4001.  
  4002. PROCEDURE GET (adr: ADDRESS; VAR v: SimpleType);
  4003. PROCEDURE PUT (adr: ADDRESS;     x: SimpleType);
  4004.  
  4005. Gets/puts a value from/to address specified by adr. The second parameter cannot 
  4006. be of a record or array type. 
  4007.  
  4008. VAR i: INTEGER;
  4009.  
  4010.   GET (128, i);   (* get system cell value *)
  4011.   i := i+20;      (* change it             *)
  4012.   PUT (128, i);   (* and put back          *)
  4013.  
  4014. PROCEDURE CODE(...);
  4015.  
  4016. The procedure is intended to embed a sequence of machine instructions directly 
  4017. into the generated code. The procedure is not implemented in the current 
  4018. release. 
  4019.  
  4020.  
  4021. ΓòÉΓòÉΓòÉ 8.6. Language extensions ΓòÉΓòÉΓòÉ
  4022.  
  4023. The appearance of the following table is a known problem and will be improved 
  4024. in the final release. 
  4025.  
  4026. |lp7.5cm|WARNING: | Using extensions may cause problems with the software 
  4027. portability to other compilers 
  4028.  
  4029. In the standard mode the XDS Modula-2 compiler is ISO compatible (See ISO 
  4030. Standard compliance). A set of language extensions may be enabled using the 
  4031. M2EXTENSIONS and M2ADDTYPES options. 
  4032.  
  4033. The main purposes of supporting the language extensions are 
  4034.  
  4035.      to improve interfacing with other languages (See Chapter Multilanguage 
  4036.       programming) 
  4037.  
  4038.      to simplify migration from Modula-2 to Oberon-2 
  4039.  
  4040.      to implement important features not found in Modula-2 
  4041.  
  4042.      to provide backward compatibility with previous releases 
  4043.  
  4044.  
  4045. ΓòÉΓòÉΓòÉ 8.6.1. Lexical extensions ΓòÉΓòÉΓòÉ
  4046.  
  4047.  
  4048. Comments 
  4049.  
  4050. The appearance of the following table is a known problem and will be improved 
  4051. in the final release. 
  4052.  
  4053. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4054.  
  4055. As well as (**), there is another valid format for comments in the source 
  4056. texts. The portion of a line from ``-'' to the end is considered as a comment. 
  4057. Example 
  4058.  
  4059.   VAR i: INTEGER; -- this is a comment
  4060. --(*
  4061.   i:=0; (* this line will be compiled *)
  4062. --*)
  4063.  
  4064. Numeric constants 
  4065.  
  4066. The appearance of the following table is a known problem and will be improved 
  4067. in the final release. 
  4068.  
  4069. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4070.  
  4071. Both Modula-2 and Oberon-2 syntax rules for the numeric and character 
  4072. representations may be used. 
  4073.  
  4074. number      =["+"|"-"]integer|real.
  4075. integer     = digit{digit}
  4076.             |octalDigit{octalDigit}"B"
  4077.             |digit{hexDigit}"X".
  4078. real        =digit{digit}"."{digit}[ScaleFactor].
  4079. ScaleFactor = ("E"|"D")["+"|"-"]digit{digit}.
  4080.  
  4081. character   ='"'char'"'|"'"char"'"
  4082.             |digit{hexDigit}"H"
  4083.             |octalDigit{octalDigit}"C".
  4084.  
  4085. Examples 
  4086.  
  4087. 1991               1991 (decimal)
  4088. 0DH                13   (decimal)
  4089. 15B                13   (decimal)
  4090. 41X                "A"
  4091. 101C               "A"
  4092.  
  4093. Note: the identifier D in the scalefactor refers to a LONGREAL value. 
  4094.  
  4095.  
  4096. ΓòÉΓòÉΓòÉ 8.6.2. Additional numeric types ΓòÉΓòÉΓòÉ
  4097.  
  4098. The appearance of the following table is a known problem and will be improved 
  4099. in the final release. 
  4100.  
  4101. |l|NOTE: Only valid when option M2ADDTYPES is set. 
  4102.  
  4103. The compiler option M2ADDTYPES allows us to use the following additional 
  4104. numeric types: 
  4105.  
  4106. The appearance of the following table is a known problem and will be improved 
  4107. in the final release. 
  4108.  
  4109. lll 1. |SHORTINT | the integers between -128 and 127 
  4110.  2. |LONGINT | the integers between -231 and 231-1 
  4111.  3. |SHORTCARD | unsigned integers between 0 and 255 
  4112.  4. |LONGCARD | unsigned integers between 0 and 232-1 
  4113.  
  4114. The following terms for groups of types will be used: 
  4115.  
  4116.  Real types  for (REAL, LONGREAL) 
  4117.  Integer types  for (SHORTINT, INTEGER, LONGINT) 
  4118.  Cardinal types  for (SHORTCARD, CARDINAL, LONGCARD) 
  4119.  Whole types  for integer  and cardinal types 
  4120.  Numeric types  for whole  and real types 
  4121.  
  4122. All the integer types are implemented as subranges of an internal compiler 
  4123. integer types. Therefore, according to the compatibility rules (See 
  4124. Compatibility), the values of different integer types can be mixed in the 
  4125. expressions. The same holds for cardinal types. A mixture of integer and 
  4126. cardinal types in expressions is not allowed. As in Oberon-2, the numeric types 
  4127. form a hierarchy, and larger types include (i.e. can accept the values of) 
  4128. smaller types:  LONGREAL ?REAL ?whole types 
  4129.  
  4130. Type compatibility in expressions is extended according to the following rules 
  4131. (See Expression compatibility): 
  4132.  
  4133.      The type of the result of an arithmetic or relation operation is the 
  4134.       smallest type which includes the types of both operands. 
  4135.  
  4136.      Before the operation, the values of both operands are converted to the 
  4137.       result's type. 
  4138.  
  4139.  If the following variables are defined : 
  4140.  
  4141.        s: SHORTCARD;
  4142.        c: CARDINAL;
  4143.        i: INTEGER;
  4144.        l: LONGINT;
  4145.        r: REAL;
  4146.        lr: LONGREAL;
  4147.  
  4148.  then 
  4149.  
  4150.  The appearance of the following table is a known problem and will be improved 
  4151.  in the final release. 
  4152.  
  4153.  |l|l|l| Expression |Meaning |Result type 
  4154.   s + c |VAL(CARDINAL,s) + c | CARDINAL 
  4155.   l * i |l * VAL(LONGINT,i) | LONGINT 
  4156.   r + 1 |r + VAL(REAL,1) | REAL 
  4157.   r = s |r = VAL(REAL,s) | BOOLEAN 
  4158.   r + lr |VAL(LONGREAL,r) + lr | LONGREAL 
  4159.   c + i |not allowed | 
  4160.  
  4161.  The assignment compatibility rules are also extended (See Assignment 
  4162.  compatibility), so an expression e of type Te is assignment compatible with a 
  4163.  variable v of type Tv if Te and Tv are of numeric types and Tv includes Te. 
  4164.  Cardinal types and integer types are assignment compatible. The compiler 
  4165.  generates the range checks whenever necessary. 
  4166.  Examples (see declarations above): 
  4167.  
  4168.  The appearance of the following table is a known problem and will be improved 
  4169.  in the final release. 
  4170.  
  4171.  |l|p7cm| Statement |Comment 
  4172.   i:=c; | INTEGER and CARDINAL are assignment compatible 
  4173.   i:=s; | INTEGER and SHORTCARD are assignment compatible 
  4174.   l:=i; | LONGINT and INTEGER are subranges of the same host type 
  4175.   r:=i; | REAL? INTEGER 
  4176.   r:=c; | REAL? CARDINAL 
  4177.   lr:=r; | LONGREAL? REAL 
  4178.  
  4179.  
  4180. ΓòÉΓòÉΓòÉ 8.6.3. Assignment compatibility with BYTE ΓòÉΓòÉΓòÉ
  4181.  
  4182. The appearance of the following table is a known problem and will be improved 
  4183. in the final release. 
  4184.  
  4185. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4186.  
  4187. Expressions of types CHAR, BOOLEAN, SHORTINT, and SYSTEM.CARD8 can be assigned 
  4188. to the variables of type BYTE or passed as actual parameters to a formal 
  4189. parameter of type BYTE. 
  4190.  
  4191.  
  4192. ΓòÉΓòÉΓòÉ 8.6.4. Dynamic arrays ΓòÉΓòÉΓòÉ
  4193.  
  4194. The appearance of the following table is a known problem and will be improved 
  4195. in the final release. 
  4196.  
  4197. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4198.  
  4199. XDS allows us to use the Oberon-2 style dynamic arrays according to the 
  4200. Oberon-2 rules. 
  4201.  
  4202. An open array is an array type with no lower and upper bound specified, i.e. 
  4203. ARRAY OF SomeType. Open arrays may be used only in procedure parameter lists or 
  4204. as a pointer base type. 
  4205.  
  4206. TYPE String = POINTER TO ARRAY OF CHAR;
  4207.  
  4208. Neither variables nor record fields may be of open array type. 
  4209.  
  4210. If the designator type is formally an open array, then the only operations 
  4211. allowed with it are indexing and passing it to a procedure. 
  4212.  
  4213. The extended versions of standard procedures NEW and DISPOSE can be used to 
  4214. create and delete the dynamic arrays (See NEW and DISPOSE for dynamic arrays). 
  4215. Example 
  4216.  
  4217. TYPE
  4218.   VECTOR = ARRAY OF REAL;
  4219.     (* 1-dim open array *)
  4220.   Vector = POINTER TO VECTOR;
  4221.     (* pointer to open array *)
  4222.   MATRIX = ARRAY OF VECTOR;
  4223.     (* 2-dim open array *)
  4224.   Matrix = POINTER TO MATRIX;
  4225.     (* pointer to this *)
  4226.  
  4227. VAR
  4228.    v: Vector;
  4229.    m: Matrix;
  4230.  
  4231. PROCEDURE ClearVector(VAR v: VECTOR);
  4232.   VAR i: CARDINAL;
  4233. BEGIN
  4234.   FOR i := 0 TO HIGH (v) DO v[i] := 0 END;
  4235. END ClearVector;
  4236.  
  4237. PROCEDURE ClearMatrix(VAR m: Matrix);
  4238.   VAR i: CARDINAL;
  4239. BEGIN
  4240.   FOR i := 0 TO HIGH (m) DO ClearVector(m[i]) END;
  4241. END ClearMatrix;
  4242.  
  4243. PROCEDURE Test;
  4244. BEGIN
  4245.   NEW(v, 10);
  4246.   NEW(m, 10, 20);
  4247.   ClearVector(v^);
  4248.   ClearMatrix(m^);
  4249.   v^[0] := 1;
  4250.   m^[1][1] := 2;
  4251.   m^[2,2] := 1000;
  4252.   DISPOSE(v);
  4253.   DISPOSE(m);
  4254. END Test;
  4255.  
  4256.  
  4257. ΓòÉΓòÉΓòÉ 8.6.5. Constant array constructors ΓòÉΓòÉΓòÉ
  4258.  
  4259. The appearance of the following table is a known problem and will be improved 
  4260. in the final release. 
  4261.  
  4262. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4263.  
  4264. XDS allows the declaration of constant arrays in the form 
  4265.  
  4266.         ARRAY OF QualIdent "{" ExprList "}".
  4267.  
  4268. QualIdent should refer to a basic type, range or enumeration type, and all 
  4269. expressions within ExprList should be of this type. 
  4270.  
  4271. Note: structured types and non-constant expressions are not allowed. 
  4272.  
  4273. The actual type of such a constant is ARRAY [0..n] OF QualIdent, where n+1 is 
  4274. the number of expressions in ExprList. 
  4275. Example 
  4276.  
  4277. CONST table = ARRAY OF INTEGER {1, 2+3, 3};
  4278.  
  4279. Constant arrays are subject to the same rules as all other constants, and may 
  4280. be read as a normal array. 
  4281.  
  4282. In some cases constructors of this form are more convenient than ISO standard 
  4283. value constructors (See Value constructors), because you do not need to declare 
  4284. a type and to calculate manually the number of expressions. However, to make 
  4285. your programs more portable, we recommend to use the standard features. 
  4286.  
  4287.  
  4288. ΓòÉΓòÉΓòÉ 8.6.6. Set complement ΓòÉΓòÉΓòÉ
  4289.  
  4290. The appearance of the following table is a known problem and will be improved 
  4291. in the final release. 
  4292.  
  4293. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4294.  
  4295. As in Oberon-2 a unary minus applied to a set denotes the complement of that 
  4296. set, i.e. -x is the set of all values which are not the elements of x. 
  4297.  
  4298. TYPE SmallSet = SET OF [0..5];
  4299. VAR x, y: SmallSet;
  4300. BEGIN
  4301.   x := SmallSet{1,3,5};
  4302.   y := -x;                  (* y = {0, 2, 4} *)
  4303.   y := SmallSet{0..5} - x;  (* y = {0, 2, 4} *)
  4304. END;
  4305.  
  4306.  
  4307. ΓòÉΓòÉΓòÉ 8.6.7. Read-only parameters ΓòÉΓòÉΓòÉ
  4308.  
  4309. The appearance of the following table is a known problem and will be improved 
  4310. in the final release. 
  4311.  
  4312. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4313.  
  4314. In a formal parameter's section, the symbol "-" may be placed after the name of 
  4315. a value parameter. Such a parameter is called read-only; its value can not be 
  4316. changed in the procedure body. Read-only parameters need not be copied before 
  4317. procedure activation; this enables generation of procedure calls with 
  4318. structured parameters to be made more effective. 
  4319.  
  4320. For ARRAY and RECORD read-only parameters, the array elements and record fields 
  4321. are protected. Read-only parameters cannot be used in the definition modules. 
  4322.  
  4323. We recommend to use read-only parameters with care. The compiler does not check 
  4324. that the read-only parameter is not modified via the another parameter or 
  4325. global variable. 
  4326. Example 
  4327.  
  4328. PROCEDURE Foo(VAR dest: ARRAY OF CHAR;
  4329.                source-: ARRAY OF CHAR);
  4330. BEGIN
  4331.   dest[0]:='a';
  4332.   dest[1]:=source[0];
  4333. END Foo;
  4334.  
  4335. The call Foo(x,x) produces the wrong result, because the first statement 
  4336. changes the value of source[0] (source is not copied and points to the same 
  4337. location as dest). 
  4338.  
  4339.  
  4340. ΓòÉΓòÉΓòÉ 8.6.8. Variable number of parameters ΓòÉΓòÉΓòÉ
  4341.  
  4342. The appearance of the following table is a known problem and will be improved 
  4343. in the final release. 
  4344.  
  4345. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4346.  
  4347. The last formal parameter in a procedure may be declared as a ``sequence of 
  4348. bytes'' (SEQ-parameter). In a procedure call, any (possibly empty) sequence of 
  4349. actual parameters may be substituted for such a parameter. Actual parameters 
  4350. corresponding to a sequence parameter may be of any type. 
  4351.  
  4352. Only the declaration 
  4353.  
  4354.      SEQ name: SYSTEM.BYTE
  4355.  
  4356. is allowed. Procedures may have only one SEQ parameter, and this must be the 
  4357. last element of the list of its formal parameters. 
  4358.  
  4359. Within the procedure, sequence parameters are very similar to ARRAY parameters. 
  4360. This means that : 
  4361.  
  4362.      HIGH function can be applied to the parameter; 
  4363.  
  4364.      a SEQ actual parameter may be subsequently passed to a further procedure 
  4365.  
  4366.      i-th byte of the sequence s can be accessed by s[i], like an array 
  4367.       element. 
  4368.  
  4369.  An array of bytes, which is passed to a procedure as a formal SEQ-parameter, 
  4370.  is formed as follows: 
  4371.  
  4372.      values of all actual parameters forming the sequence are represented as 
  4373.       described below and concatenated in an array in their textual order 
  4374.  
  4375.      integer values are converted to LONGINT 
  4376.  
  4377.      BOOLEAN, CHAR, cardinal and enumeration values are converted to LONGCARD 
  4378.  
  4379.      values of the range types are converted according to their base type 
  4380.  
  4381.      real values are converted to LONGREAL 
  4382.  
  4383.      values of pointer, opaque and procedure types are converted to ADDRESS 
  4384.  
  4385.      a structured value (record or array) is interpreted as an array of bytes 
  4386.       and passed as a sequence of: 
  4387.  
  4388.         -  address of a structure 
  4389.  
  4390.         -  zero word (reserved for future extensions) 
  4391.  
  4392.         -  size of a structure (in LOCs) minus one 
  4393.  
  4394.  See Sequence parameters for further information. 
  4395.  
  4396.  
  4397. ΓòÉΓòÉΓòÉ 8.6.9. Read-only export ΓòÉΓòÉΓòÉ
  4398.  
  4399. The appearance of the following table is a known problem and will be improved 
  4400. in the final release. 
  4401.  
  4402. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4403.  
  4404. The Oberon-2 read-only export symbol "-", after a variable or field identifier 
  4405. in a definition module will define the identifier as read-only for any client. 
  4406. Only the module in which a read-only identifier is declared may change its 
  4407. value. 
  4408.  
  4409. The compiler will not allow the value of read-only exported object to be 
  4410. changed explicitly (by an assignment) or implicitly (passing as a VAR 
  4411. parameter). 
  4412.  
  4413. For read-only variables of an array or record type, both array elements and 
  4414. record fields are also read-only. 
  4415. Example (extract from definition module): 
  4416.  
  4417. TYPE Rec = RECORD
  4418.   n-: INTEGER;
  4419.   m : INTEGER;
  4420. END;
  4421.  
  4422. VAR
  4423.   in-: FILE;
  4424.   x-: Rec;
  4425.  
  4426.  
  4427. ΓòÉΓòÉΓòÉ 8.6.10. Renaming of imported modules ΓòÉΓòÉΓòÉ
  4428.  
  4429. The appearance of the following table is a known problem and will be improved 
  4430. in the final release. 
  4431.  
  4432. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4433.  
  4434. An imported module can be renamed inside an importing module. The real name of 
  4435. the module becomes invisible. 
  4436.  
  4437. Import = IMPORT [ Ident ":=" ] Ident
  4438.           { "," [ Ident ":=" ] ident } ";".
  4439.  
  4440. Example 
  4441.  
  4442. MODULE test;
  4443. IMPORT vw := VirtualWorkstation;
  4444.  
  4445. VAR ws: vw.Station;
  4446.  
  4447. BEGIN
  4448.   ws := vw.open();
  4449. END test.
  4450.  
  4451.  
  4452. ΓòÉΓòÉΓòÉ 8.6.11. NEW and DISPOSE for dynamic arrays ΓòÉΓòÉΓòÉ
  4453.  
  4454. Standard procedures NEW and DISPOSE can be applied to the variables of a 
  4455. dynamic array type (See Dynamic arrays). In this case procedures DYNALLOCATE 
  4456. and DYNDEALLOCATE should be visible in the calling context. 
  4457.  
  4458. PROCEDURE DYNALLOCATE(VAR a: ADDRESS;
  4459.                        size: CARDINAL;
  4460.                         len: ARRAY OF CARDINAL);
  4461.  
  4462. The procedure must allocate a dynamic array, where size is the size of array 
  4463. base type (the size of an element) and len[i] is the length of the array in 
  4464. i-th dimension. 
  4465.  
  4466. PROCEDURE DYNDEALLOCATE(VAR a: ADDRESS;
  4467.                      size,dim: CARDINAL);
  4468.  
  4469. The procedure must deallocate a dynamic array, where size is the size of an 
  4470. element and dim is the number of dimensions. 
  4471.  
  4472. Dynamic arrays are represented as a pointer to the so-called array descriptor 
  4473. (See Array types). 
  4474.  
  4475.  
  4476. ΓòÉΓòÉΓòÉ 8.6.12. HALT ΓòÉΓòÉΓòÉ
  4477.  
  4478. The appearance of the following table is a known problem and will be improved 
  4479. in the final release. 
  4480.  
  4481. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4482.  
  4483. An optional integer parameter is allowed for the HALT procedure. 
  4484.  
  4485. PROCEDURE HALT ([code: INTEGER]);
  4486.  
  4487. HALT terminates the program execution with an optional return code. Consult 
  4488. your operating system/environment documentation for more details. 
  4489.  
  4490.  
  4491. ΓòÉΓòÉΓòÉ 8.6.13. ASSERT ΓòÉΓòÉΓòÉ
  4492.  
  4493. The appearance of the following table is a known problem and will be improved 
  4494. in the final release. 
  4495.  
  4496. |l|NOTE: Only valid when option M2EXTENSIONS is set. 
  4497.  
  4498. The procedure ASSERT checks its boolean parameter and terminates the program if 
  4499. it is not TRUE. The second optional parameter denotes task termination code. If 
  4500. it is omitted, a standard value is assumed. 
  4501.  
  4502. PROCEDURE ASSERT(cond: BOOLEAN [; code: INTEGER]);
  4503.  
  4504. The call ASSERT(expr,code) is equal to 
  4505.  
  4506. IF NOT expr THEN HALT(code) END;
  4507.  
  4508.  
  4509. ΓòÉΓòÉΓòÉ 8.7. Source code directives ΓòÉΓòÉΓòÉ
  4510.  
  4511. Source code directives (or pragmas) are used for setting of compilation options 
  4512. in the source text and for selection of the specific source text to be compiled 
  4513. (conditional compilation). The ISO Modula-2 standard does not describe the 
  4514. syntax of pragmas. XDS allows one to use source code directives in both 
  4515. Modula-2 and Oberon-2. The syntax described in The Oakwood Guidelines for the 
  4516. Oberon-2 Compiler Developers is used. 
  4517.  
  4518.  
  4519. ΓòÉΓòÉΓòÉ 8.7.1. Inline options ΓòÉΓòÉΓòÉ
  4520.  
  4521. In some cases it is more preferable to set the compiler options within the 
  4522. source text. Some compiler options such as MAIN are more meaningful there. 
  4523.  
  4524. XDS allows options to be changed in source text by using standard ISO pseudo 
  4525. comments <* ... *>The old style of pragmas (*\$..*) is supported to provide 
  4526. backward compatibility, but the compiler reports ``obsolete syntax'' warning. 
  4527. Some options can only be placed in source text before the module header (i.e. 
  4528. before keywords IMPLEMENTATION, DEFINITION or MODULE). These options will be 
  4529. ignored if found elsewhere in the source text. See Description of options for 
  4530. more details. 
  4531.  
  4532. The format of an inline option setting is described by the following syntax: 
  4533.  
  4534. The appearance of the following table is a known problem and will be improved 
  4535. in the final release. 
  4536.  
  4537. l@= l PragmaBody | <* Switch *> 
  4538.  Switch | NewStyle | OldStyle | PragmaStyle 
  4539.  NewStyle | [ NEW ] name [ '+' | '-' ] 
  4540.  OldStyle | ('+' | '-') name 
  4541.  PragmaStyle | '$'  Modifier 
  4542.  Modifier | name '+' | name '-' | > | < | ! 
  4543.  
  4544. The NewStyle and PragmaStyle PragmaStyle is an extention of Oakwood standard - 
  4545. option names are used instead of pragma letters.  are proposed as the Oakwood 
  4546. standard for Oberon-2, OldStyle is the style used in the previous XDS release. 
  4547. All option names are case-independent. In the OldStyle and PragmaStyle there 
  4548. should be no space between <* and +, - or $. 
  4549.  
  4550. In all cases the symbol + sets the corresponding option ON, and the symbol - 
  4551. sets it OFF. In the pragmaStyle special modifiers have the following meaning: 
  4552.  
  4553.  <         saves the current option's state 
  4554.  
  4555.  >         restores the last saved option's state 
  4556.  
  4557.  !         restore option's state set prior to the compilation of the given 
  4558.            module 
  4559.  
  4560.  Example 
  4561.  
  4562.   PROCEDURE Length(VAR a: ARRAY OF CHAR): CARDINAL;
  4563.     VAR i: CARDINAL;
  4564.   BEGIN
  4565.     <*$<*>              (* save state *)
  4566.     <* CHECKINDEX - *>  (* turn CHECKINDEX off *)
  4567.     i := 0;
  4568.     WHILE (i<=HIGH(a)) & (a[i]#0C) DO INC(i) END;
  4569.     <*$>*>   (* restore option's state *)
  4570.     RETURN i;
  4571.   END Length;
  4572.  
  4573.  
  4574. ΓòÉΓòÉΓòÉ 8.7.2. Conditional compilation ΓòÉΓòÉΓòÉ
  4575.  
  4576. It is possible to use the conditional compilation with Modula-2 and 
  4577. Oberon-2only if the O2ISOPRAGMA option is set ON compilers via the standard ISO 
  4578. pragma notation <* *>. Conditional compilation statements can be placed 
  4579. anywhere in the source code. The syntax of the conditional compilation IF 
  4580. statement: 
  4581.  
  4582.   IfStatement      = <* IF Expression THEN *>  text
  4583.                    { <* ELSIF Expression THEN *> text }
  4584.                    [ <* ELSE *> text ]
  4585.                      <* END *>
  4586.   Expression       = SimpleExpression
  4587.                      [ ("=" | "#") SimpleExpression].
  4588.   SimpleExpression = Term { "OR" Term}.
  4589.   Term             = Factor { "&" Factor}.
  4590.   Factor           = ident | string |
  4591.                      "DEFINED" "(" ident ")" |
  4592.                      "(" Expression ")" |
  4593.                      "~" Factor | "NOT" Factor.
  4594.   ident            = option | equation.
  4595.  
  4596. An operand in an expressions is either a name of option or equation or a string 
  4597. literal. An option has the value TRUE, if it was set to TRUE in the 
  4598. configuration or project file, on the command line, or within the source text. 
  4599. An option has the value FALSE, if it was set to FALSE explicitly or was not 
  4600. defined at all. The compiler will report a warning if an undeclared option or 
  4601. equation is used as a conditional compilation identifier. 
  4602. Examples 
  4603.  
  4604.   IMPORT lib :=
  4605.         <* IF  __GEN_X86__ THEN *> MyX86Lib;
  4606.         <* ELSIF __GEN_C__ THEN *> MyCLib;
  4607.         <* ELSE *> *** Unknown ***
  4608.         <* END *>
  4609.  
  4610.   CONST Win = <* IF Windows THEN *> TRUE
  4611.               <* ELSE *> FALSE
  4612.               <* END *>;
  4613.  
  4614.   <* IF DEFINED(Debug) & (DebugLevel = "2") THEN *>
  4615.      PrintDebugInformation;
  4616.   <* END *>;
  4617.  
  4618.   <* IF platform = "OS2" THEN *>
  4619.     Strings.Capitalize(filename);
  4620.     <* IF NOT HPFS THEN *>
  4621.       TruncateFileName(filename);
  4622.     <* END *>
  4623.   <* END *>
  4624.  
  4625.  
  4626. ΓòÉΓòÉΓòÉ 9. XDS Oberon-2 ΓòÉΓòÉΓòÉ
  4627.  
  4628. This chapter includes the details of the Oberon-2 language which are specific 
  4629. for this implementation. In the standard mode When the options O2EXTENSIONS and 
  4630. O2NUMEXT are OFF. XDS Oberon-2 is fully compatible with ETH compilers (See 
  4631. Appendix The Oberon-2 Report for the language report). The last changes of the 
  4632. language are described in Last changes to the language. 
  4633.  
  4634. To provide a smooth path from Modula-2 to Oberon-2 XDS allows all Modula-2 data 
  4635. types to be used in Oberon-2 modules (See Using Modula-2 features). 
  4636.  
  4637. Several language extensions are implemented in the language according to The 
  4638. Oakwood Guidelines for the Oberon-2 Compiler Developers These guidelines have 
  4639. been produced by a group of Oberon-2 compiler developers, including ETH 
  4640. developers, after a meeting at the Oakwood Hotel in Croydon, UK in June 1993. 
  4641. (See Oakwood numeric extensions). Other language extensions are described in 
  4642. Language extensions. As XDS is a truly multi-lingual system, special features 
  4643. were introduced to provide for foreign language interfaces (See Chapter 
  4644. Multilanguage programming). 
  4645.  
  4646.  
  4647. ΓòÉΓòÉΓòÉ 9.1. The Oberon environment ΓòÉΓòÉΓòÉ
  4648.  
  4649. The Oberon-2 language was originally designed for use in an environment that 
  4650. provides the command activation, garbage collection, and dynamic loading of the 
  4651. modules. Although not being a part of the language, these features contribute 
  4652. to the power of Oberon-2. 
  4653.  
  4654. The garbage collector and command activation are implemented in the Oberon 
  4655. Run-Time Support and can be used in any program. The dynamic loader is not 
  4656. provided in the current release. See The oberonRTS module for further 
  4657. information. 
  4658.  
  4659.  
  4660. ΓòÉΓòÉΓòÉ 9.1.1. Program structure ΓòÉΓòÉΓòÉ
  4661.  
  4662. In the Oberon-2 environment, any declared parameterless procedure can be 
  4663. considered as a main procedure and can be called by its name (a qualified 
  4664. identifier of the form ModuleName.ProcName). 
  4665.  
  4666. Due to the nature of XDS, and its freedom from the Oberon system, a different 
  4667. approach is to be taken to declare the `top level' or program modules. 
  4668.  
  4669. The module which contains the top level of your program must be declared as 
  4670. such by translating it with the MAIN option set. This will generate an entry 
  4671. point to your program. Only one module per program shall be compiled with the 
  4672. option set. 
  4673.  
  4674.  
  4675. ΓòÉΓòÉΓòÉ 9.1.2. Creating a definition ΓòÉΓòÉΓòÉ
  4676.  
  4677. XDS provides two different ways to create a definition for Oberon-2 module: 
  4678.  
  4679.      the BROWSE operation mode creates a definition module from a symbol file 
  4680.       (See BROWSE mode); 
  4681.  
  4682.      the MAKEDEF option forces the Oberon compiler to generate a (pseudo) 
  4683.       definition module after a successful compilation of an Oberon module. 
  4684.  
  4685.  The MAKEDEF option provides additional services: the compiler will preserve 
  4686.  the so-called exported comments (i.e. comments which start with `(**') if the 
  4687.  XCOMMENTS option is set. 
  4688.  
  4689.  The generated pseudo-definition module contains all exported declarations in 
  4690.  the order of appearance in the source text. All exported comments are placed 
  4691.  in the appropriate positions. 
  4692.  
  4693.  The definition module can be generated in three styles.The BSTYLE equation can 
  4694.  be used to choose one of the styles: DEF (default), DOC or MOD. 
  4695.  
  4696.  The DEF style 
  4697.  
  4698.            This produces an ETH-style definition module. All type-bound 
  4699.            procedures (methods) and relative comments are shown as a part of 
  4700.            the corresponding record type. 
  4701.  
  4702.            This is the only style for which the BSREDEFINE and BSCLOSURE 
  4703.            options are applicable. 
  4704.  
  4705.  The DOC style 
  4706.  
  4707.            This produces a pseudo-definition module in which methods are shown 
  4708.            as a part of an appropriate record type (ignoring comments) and in 
  4709.            the same positions as they occur in the source text. 
  4710.  
  4711.  The MOD style 
  4712.  
  4713.            This attempts to produce a file which can be compiled as an Oberon 
  4714.            module after a slight modification (i.e.the file will contain "END 
  4715.            procname" etc.) 
  4716.  
  4717.  
  4718. ΓòÉΓòÉΓòÉ 9.2. Last changes to the language ΓòÉΓòÉΓòÉ
  4719.  
  4720.  
  4721. ΓòÉΓòÉΓòÉ 9.2.1. ASSERT ΓòÉΓòÉΓòÉ
  4722.  
  4723. The procedure ASSERT checks its boolean parameter and terminates the program if 
  4724. it is not TRUE. The second optional parameter denotes task termination code. If 
  4725. omitted, a standard value is assumed. 
  4726.  
  4727. PROCEDURE ASSERT(cond: BOOLEAN [; code: INTEGER]);
  4728.  
  4729. The call ASSERT(expr,code) is equal to 
  4730.  
  4731. IF NOT expr THEN HALT(code) END;
  4732.  
  4733.  
  4734. ΓòÉΓòÉΓòÉ 9.2.2. Underscores in identifiers ΓòÉΓòÉΓòÉ
  4735.  
  4736. According to the Oakwood Guidelines an underscore "_" may be used in 
  4737. identifiers (as a letter). 
  4738.  
  4739. ident = ( letter | "_" ) { letter | digit | "_" }.
  4740.  
  4741. We recommend to use underscores with care, as it may cause problems with the 
  4742. software portability to other compilers. This feature may be important when 
  4743. interfacing with foreign languages (See Chapter Multilanguage programming). 
  4744.  
  4745.  
  4746. ΓòÉΓòÉΓòÉ 9.2.3. Source code directives ΓòÉΓòÉΓòÉ
  4747.  
  4748. Source code directives (or pragmas) are used for setting of compilation options 
  4749. in the source text and for selection of the specific source text to be compiled 
  4750. (conditional compilation). According to the Oakwood Guidelines all directives 
  4751. are contained in ISO Modula-2 style pseudo comments using angled brackets <* 
  4752. ... *>. 
  4753.  
  4754. The additional language constructs should not be considered to be part of the 
  4755. Oberon-2 languages. Rather they defined a separate compiler control language 
  4756. that coexist with Oberon-2. The option O2ISOPRAGMA allows one to use pragmas. 
  4757.  
  4758. The syntax of the directives is the same for Modula-2 and Oberon-2. See Source 
  4759. code directives for further details. 
  4760.  
  4761.  
  4762. ΓòÉΓòÉΓòÉ 9.3. Oakwood numeric extensions ΓòÉΓòÉΓòÉ
  4763.  
  4764. XDS Oberon-2 supports two extensions which are of importance for scientific 
  4765. programming, namely 
  4766.  
  4767.      complex numbers 
  4768.  
  4769.      in-line exponentiation operator 
  4770.  
  4771.  The O2NUMEXT option should be set to use these extensions. 
  4772.  
  4773.  
  4774. ΓòÉΓòÉΓòÉ 9.3.1. Complex numbers ΓòÉΓòÉΓòÉ
  4775.  
  4776. The appearance of the following table is a known problem and will be improved 
  4777. in the final release. 
  4778.  
  4779. |l|NOTE: Only valid when option O2NUMEXT is set. 
  4780.  
  4781. Two additional types are included in the type hierarchy if the O2NUMEXT option 
  4782. is set: 
  4783.  
  4784. The appearance of the following table is a known problem and will be improved 
  4785. in the final release. 
  4786.  
  4787. lcl COMPLEX | defined as | (REAL,REAL) 
  4788.  LONGCOMPLEX | defined as | (LONGREAL,LONGREAL) 
  4789.  
  4790. All numeric types form a (partial) hierarchy  LONGCOMPLEX ? 
  4791.  
  4792. l COMPLEX 
  4793.  LONGREAL 
  4794.  ? 
  4795.  
  4796. REAL ?whole types  A common mathematical notation is used for complex number 
  4797. literals: 
  4798.  
  4799. number = integer | real | complex.
  4800. complex = real "i".
  4801.  
  4802. A literal of the form 5.0i denotes a complex number with real part equal to 
  4803. zero and an imaginary part equal to 5.0. Complex constants with a non-zero real 
  4804. part can be described using arithmetic operators. 
  4805.  
  4806. CONST
  4807.   i = 1.i;
  4808.   x = 1. + 1.i;
  4809.  
  4810. For the declarations 
  4811.  
  4812. VAR
  4813.   c: COMPLEX;
  4814.   l: LONGCOMPLEX;
  4815.   r: REAL;
  4816.   x: INTEGER;
  4817.  
  4818. the following statements are valid: 
  4819.  
  4820.   c:=i+r;
  4821.   l:=c;
  4822.   l:=c*r;
  4823.   l:=l*c;
  4824.  
  4825. New conversion functions RE and IM can be used to obtain a real or imaginary 
  4826. part of a value of a complex type. Both functions have one parameter. If the 
  4827. parameter is of the COMPLEX type, both functions return the REAL value; if the 
  4828. parameter is of the LONGCOMPLEX type, functions return the LONGREAL value; 
  4829. otherwise the parameter should be a complex constant and functions return real 
  4830. constant. 
  4831.  
  4832. A complex value can be formed by applying the standard function CMPLX to two 
  4833. reals. If both CMPLX arguments are real constants, the result is a complex 
  4834. constant. 
  4835.  
  4836. CONST i = CMPLX(0.0,1.0);
  4837.  
  4838. If both expressions are of the REAL type, the function returns the COMPLEX 
  4839. value, otherwise it returns the LONGCOMPLEX value. 
  4840.  
  4841.  
  4842. ΓòÉΓòÉΓòÉ 9.3.2. In-line exponentiation ΓòÉΓòÉΓòÉ
  4843.  
  4844. The appearance of the following table is a known problem and will be improved 
  4845. in the final release. 
  4846.  
  4847. |l|NOTE: Only valid when option O2NUMEXT is set. 
  4848.  
  4849. The exponentiation operator ** provides a convenient notation for arithmetic 
  4850. expressions, rather than using function calls. It is an arithmetic operator 
  4851. which has a higher precedence than multiplication operators. 
  4852.  
  4853. Term     =  Exponent { MulOp Exponent }.
  4854. Exponent =  Factor { "**" Factor }.
  4855.  
  4856. Note: the operator is right-associated:  a**b**c  is evaluated as  abc 
  4857.  
  4858. The left operand of the exponentiation (a**b) should be any numeric value 
  4859. (including complex), while the right operand should be of a real or integer 
  4860. type. The result type does not depend of the type of right operand and is 
  4861. defined by the table: 
  4862.  
  4863. The appearance of the following table is a known problem and will be improved 
  4864. in the final release. 
  4865.  
  4866. |l|l| Type of left operand | Result type 
  4867.  integer type | REAL 
  4868.  REAL | REAL 
  4869.  LONGREAL | LONGREAL 
  4870.  COMPLEX | COMPLEX 
  4871.  LONGCOMPLEX | LONGCOMPLEX 
  4872.  
  4873.  
  4874. ΓòÉΓòÉΓòÉ 9.4. Using Modula-2 features ΓòÉΓòÉΓòÉ
  4875.  
  4876. All Modula-2 types and corresponding operations can be used in Oberon-2, 
  4877. including enumeration types, range types, records with variant parts, sets, 
  4878. etc. 
  4879. Important Notes: 
  4880.  
  4881.      It is not allowed to declare the Modula-2 types in an Oberon-2 module. 
  4882.  
  4883.      A module using Modula-2 features may be non-portable to other compilers. 
  4884.  
  4885.  Example 
  4886.  
  4887.   (*MODULA-2*) DEFINITION MODULE UsefulTypes;
  4888.  
  4889.   TYPE
  4890.     TranslationTable = ARRAY CHAR OF CHAR;
  4891.     Color  = (red,green,blue);
  4892.     Colors = SET OF Color;
  4893.  
  4894.   END UsefulTypes.
  4895.  
  4896.   (*OBERON-2*) MODULE UsingM2;
  4897.  
  4898.   IMPORT UsefulTypes;
  4899.  
  4900.   TYPE
  4901.     TranslationTable* = UsefulTypes.TranslationTable;
  4902.  
  4903.   VAR colors*: UsefulTypes.Color;
  4904.  
  4905.   BEGIN
  4906.     colors:=UsefulTypes.Colors{UsefulTypes.red};
  4907.   END UsingM2.
  4908.  
  4909.  
  4910. ΓòÉΓòÉΓòÉ 9.5. Language extensions ΓòÉΓòÉΓòÉ
  4911.  
  4912. The appearance of the following table is a known problem and will be improved 
  4913. in the final release. 
  4914.  
  4915. |lp7.5cm|WARNING: | Using extensions may cause problems with the software 
  4916. portability to other compilers. 
  4917.  
  4918. In the standard mode the XDS Oberon-2 compiler is fully compatible with ETH 
  4919. compilers (See also Last changes to the language). The O2EXTENSIONS option 
  4920. enables some language extensions. The main purposes of language extensions are 
  4921.  
  4922.      to improve interfacing with other languages (See Chapter Multilanguage 
  4923.       programming). 
  4924.  
  4925.      to provide backward compatibility with the previous versions of XDS. 
  4926.  
  4927.   See also 
  4928.  
  4929.      Source language directives (Source code directives) 
  4930.  
  4931.      Oakwood numeric extensions (Oakwood numeric extensions). 
  4932.  
  4933.  
  4934. ΓòÉΓòÉΓòÉ 9.5.1. Comments ΓòÉΓòÉΓòÉ
  4935.  
  4936. The appearance of the following table is a known problem and will be improved 
  4937. in the final release. 
  4938.  
  4939. |l|NOTE: Only valid when option O2EXTENSIONS is set. 
  4940.  
  4941. As well as "(**)", there is another valid format for comments in source texts. 
  4942. The portion of a line from "-" to the end is considered as a comment. 
  4943. Example 
  4944.  
  4945. VAR j: INTEGER; -- this is a comment
  4946.  
  4947.  
  4948. ΓòÉΓòÉΓòÉ 9.5.2. String concatenation ΓòÉΓòÉΓòÉ
  4949.  
  4950. The appearance of the following table is a known problem and will be improved 
  4951. in the final release. 
  4952.  
  4953. |l|NOTE: Only valid when option O2EXTENSIONS is set. 
  4954.  
  4955. The symbol "+" can be used for constant string and characters concatenation. 
  4956. See Strings for more details. 
  4957.  
  4958.  
  4959. ΓòÉΓòÉΓòÉ 9.5.3. VAL function ΓòÉΓòÉΓòÉ
  4960.  
  4961. The appearance of the following table is a known problem and will be improved 
  4962. in the final release. 
  4963.  
  4964. |l|NOTE: Only valid when option O2EXTENSIONS is set. 
  4965.  
  4966. The function VAL can be used to obtain a value of a specified scalar type from 
  4967. an expression of a scalar type. See Type conversions for more details. 
  4968.  
  4969. PROCEDURE VAL(Type; expr: ScalarType): Type;
  4970.  
  4971. The function can be applied to any scalar types, including the system fixed 
  4972. size types (See Whole system types). 
  4973.  
  4974.  
  4975. ΓòÉΓòÉΓòÉ 9.5.4. Read-only parameters ΓòÉΓòÉΓòÉ
  4976.  
  4977. The appearance of the following table is a known problem and will be improved 
  4978. in the final release. 
  4979.  
  4980. |l|NOTE: Only valid when option O2EXTENSIONS is set. 
  4981.  
  4982. In a formal parameter's section, the symbol "-" may stand after the name of a 
  4983. value parameter. Such a parameter is called read-only; its value can not be 
  4984. changed in the procedure's body. Read-only parameters need not be copied before 
  4985. the procedure activation; this enables the generation of procedure calls with 
  4986. structured parameters to be made more effective. Read-only parameters can not 
  4987. be used in a procedure type declaration. 
  4988.  
  4989. We recommend to use read-only parameters with care. The compiler does not check 
  4990. that the read-only parameter is not modified via the another parameter or 
  4991. global variable. 
  4992. Example 
  4993.  
  4994. PROCEDURE Foo(VAR dest: ARRAY OF CHAR;
  4995.                source-: ARRAY OF CHAR);
  4996. BEGIN
  4997.   dest[0]:='a';
  4998.   dest[1]:=source[0];
  4999. END Foo;
  5000.  
  5001. The call Foo(x,x) produces the wrong result, because the first statement 
  5002. changes the value of source[0] (source is not copied and points to the same 
  5003. location as dest). 
  5004.  
  5005.  
  5006. ΓòÉΓòÉΓòÉ 9.5.5. Variable number of parameters ΓòÉΓòÉΓòÉ
  5007.  
  5008. The appearance of the following table is a known problem and will be improved 
  5009. in the final release. 
  5010.  
  5011. |l|NOTE: Only valid when option O2EXTENSIONS is set. 
  5012.  
  5013. Everything contained in section Variable number of parameters is applicable to 
  5014. Oberon-2. 
  5015.  
  5016.  
  5017. ΓòÉΓòÉΓòÉ 9.6. The module SYSTEM ΓòÉΓòÉΓòÉ
  5018.  
  5019. Low level facilities are provided by the module SYSTEM. This module does not 
  5020. exist in the same sense as other libraries but is hard-coded into the compiler 
  5021. itself. However, to use the facilities provided, identifiers must be imported 
  5022. in the usual way. 
  5023.  
  5024. Some procedures in the module SYSTEM are generic procedures that cannot be 
  5025. explicitly declared, i.e. they apply to classes of operand types. 
  5026.  
  5027. XDS Oberon-2 compiler implements all system features described in Appendix The 
  5028. Oberon-2 Report (except GETREG, PUTREG and CC) and allows one to access to all 
  5029. features, described in the International Standard of Modula-2 (See The module 
  5030. SYSTEM). In this section we describe only features specific for this 
  5031. implementation. 
  5032.  
  5033.  
  5034. ΓòÉΓòÉΓòÉ 9.6.1. Compatibility with BYTE ΓòÉΓòÉΓòÉ
  5035.  
  5036. Expressions of types CHAR, BOOLEAN, SHORTINT and SYSTEM.CARD8 can be assigned 
  5037. to the variables of type BYTE or passed as actual parameters to formal 
  5038. parameters of type BYTE. 
  5039.  
  5040. If a formal variable parameter is of type ARRAY OF BYTE then the corresponding 
  5041. actual parameter may be of any type, except numeric literals. 
  5042.  
  5043.  
  5044. ΓòÉΓòÉΓòÉ 9.6.2. Whole system types ΓòÉΓòÉΓòÉ
  5045.  
  5046. Module SYSTEM contains the signed types INT8, INT16, INT32 and unsigned types 
  5047. CARD8, CARD16, CARD32, which are guaranteed to contain exactly 8, 16, or 32 
  5048. bits respectively. These types were introduced to simplify consstructing the 
  5049. interfaces to foreign libraries (See Chapter Multilanguage programming). The 
  5050. basic types SHORTINT, INTEGER, LONGINT are synonyms of INT8, INT16 and INT32 
  5051. respectively. 
  5052.  
  5053. The unsigned types form a hierarchy whereby larger types include (the values 
  5054. of) smaller types.  SYSTEM.CARD32 ?SYSTEM.CARD16 ?SYSTEM.CARD8  The whole 
  5055. hierarchy of numeric types (See also Complex numbers):  LONGREAL ?REAL ?{ 
  5056.  
  5057. l signed types 
  5058.  unsigned types 
  5059.  
  5060. . 
  5061.  
  5062.  
  5063. ΓòÉΓòÉΓòÉ 9.6.3. NEW and DISPOSE ΓòÉΓòÉΓòÉ
  5064.  
  5065. The procedure SYSTEM.NEW can be used to allocate the system memory, i.e. memory 
  5066. which is not the subject of garbage collection. SYSTEM.NEW is a generic 
  5067. procedure, which is applied to pointer types and can be used in several ways, 
  5068. depending on pointer's base type. 
  5069.  
  5070. PROCEDURE NEW(VAR p: AnyPointer [; x0,..xn: integer]);
  5071.  
  5072. Let P be defined as POINTER TO T and p is of type T. 
  5073.  
  5074. The appearance of the following table is a known problem and will be improved 
  5075. in the final release. 
  5076.  
  5077. lp7.5cm NEW(p) | T is a record or fixed length array type. The procedure 
  5078. allocates a storage block of SIZE(p'136) bytes and assigns its address to p. 
  5079.  
  5080. NEW(p,n) | T is a record or fixed length array type. The procedure allocates a 
  5081. storage block of n bytes and assigns its address to p. 
  5082.  NEW(p,x0,..xn-1) | T is n-dimensional open array. The procedure allocates an 
  5083. open array of lengths given by the expressions x0,..xn-1 
  5084.  
  5085. Procedure SYSTEM.DISPOSE can be used to free the block allocated by the call of 
  5086. SYSTEM.NEW. It does not immediately deallocate the block, but marks it as a 
  5087. free block. Such a block will be deallocated by the next call of the garbage 
  5088. collector. 
  5089.  
  5090. PROCEDURE DISPOSE(VAR p: AnyPointer; [size: integer]);
  5091.  
  5092. The appearance of the following table is a known problem and will be improved 
  5093. in the final release. 
  5094.  
  5095. lp7.5cm DISPOSE(p) | T is a record or array type. The procedure deallocates 
  5096. storage block for pointer p. 
  5097.  DISPOSE(p,n) | T is record or fixed length array type. The procedure 
  5098. deallocates storage block of n bytes. 
  5099.  
  5100.  
  5101. ΓòÉΓòÉΓòÉ 10. Multilanguage programming ΓòÉΓòÉΓòÉ
  5102.  
  5103. XDS allows the programmer to mix Modula-2, Oberon-2, C and Assembler modules, 
  5104. libraries, and object files in one project. 
  5105.  
  5106.  
  5107. ΓòÉΓòÉΓòÉ 10.1. Modula-2 and Oberon-2 ΓòÉΓòÉΓòÉ
  5108.  
  5109. It is not necessary to notify the compiler of using Modula-2 objects in 
  5110. Oberon-2 module and vice versa. The compiler will detect the language 
  5111. automatically when processing symbol files on IMPORT clause. 
  5112.  
  5113.  
  5114. ΓòÉΓòÉΓòÉ 10.1.1. Basic types ΓòÉΓòÉΓòÉ
  5115.  
  5116. In Oberon-2 the basic types have the same length on all platforms. In Modula-2 
  5117. the size of types INTEGER, CARDINAL and BITSET may be different and depends on 
  5118. the value of the M2BASE16 option. The following table summarizes the 
  5119. correspondence between the basic types. 
  5120.  
  5121. The appearance of the following table is a known problem and will be improved 
  5122. in the final release. 
  5123.  
  5124. |l|c|c|c|c| Type | Size | Oberon-2 | 2c|Modula-2 
  5125.  | | | M2BASE16+ | M2BASE16- 
  5126.  integer | 8 | SHORTINT | - | - 
  5127.  integer | 16 | INTEGER | INTEGER | - 
  5128.  integer | 32 | LONGINT | - | INTEGER 
  5129.  cardinal | 8 | - | - | - 
  5130.  cardinal | 16 | - | CARDINAL | - 
  5131.  cardinal | 32 | - | - | CARDINAL 
  5132.  bitset | 16 | - | BITSET | - 
  5133.  bitset | 32 | SET | - | BITSET 
  5134.  
  5135. The system types INT and CARD correspond to Modula-2 INTEGER and CARDINAL types 
  5136. respectively. We recommend to use INT and CARD in Oberon-2 when importing 
  5137. Modula-2 modules. For example, if the procedure Foo is defined in the Modula-2 
  5138. definition module as 
  5139.  
  5140. DEFINITION MODULE M;
  5141.  
  5142. PROCEDURE Foo(VAR x: INTEGER);
  5143.  
  5144. END M.
  5145.  
  5146. the portable usage of this procedure in Oberon-2 is as follows: 
  5147.  
  5148.  VAR x: SYSTEM.INT;
  5149.   ...
  5150.   M.Foo(x);
  5151.  
  5152.  
  5153. ΓòÉΓòÉΓòÉ 10.1.2. Data structures ΓòÉΓòÉΓòÉ
  5154.  
  5155. XDS allows any Modula-2 data structures to be used in Oberon-2 modules, even 
  5156. those that can not be defined in Oberon-2 (that is variant records, range 
  5157. types, set types, enumerations, etc). 
  5158.  
  5159. However, the use of Modula-2 types in Oberon-2 and vice versa is restricted. 
  5160. Whenever possible XDS tries to produce the correct code. If a correct 
  5161. translation is impossible, an error is reported: 
  5162.  
  5163.      a Modula-2 record field type cannot be of an Oberon-2 pointer, record or 
  5164.       array type; 
  5165.  
  5166.      Modula-2 pointer to Oberon-2 record cannot be used in specific Oberon-2 
  5167.       constructs (type-bound procedures, type guards, etc); 
  5168.  
  5169.      an opaque type can not be defined as an Oberon pointer. 
  5170.  
  5171.  Standard procedures NEW and DISPOSE are always applied according to the 
  5172.  language of a parameter's type. For example, for the following declarations in 
  5173.  the Oberon-2 module: 
  5174.  
  5175.   TYPE
  5176.     Rec = RECORD END;
  5177.     MP  = POINTER ["Modula"] TO Rec; (* Modula pointer *)
  5178.     OP  = POINTER TO Rec;     (* Oberon pointer *)
  5179.   VAR
  5180.     m: MP;
  5181.     o: OP;
  5182.  
  5183.  The call of NEW(m) will be treated as a call of the Modula-2 default ALLOCATE, 
  5184.  while NEW(o) will be treated as a call of the standard Oberon run-time 
  5185.  routine. See also Direct language specification. 
  5186.  
  5187.  An implicit memory deallocation (garbage collection) is applied to Oberon-2 
  5188.  objects only. If a variable of the Modula-2 pointer type is declared in the 
  5189.  Oberon-2 module, it shall be deallocated explicitly. 
  5190.  Example: Using the Modula data type in Oberon 
  5191.  
  5192.   (* Modula-2*) DEFINITION MODULE m2;
  5193.   TYPE
  5194.     Rec = RECORD  (* a record with variant parts *)
  5195.       CASE tag: BOOLEAN OF
  5196.         |TRUE:  i: INTEGER;
  5197.         |FALSE: r: REAL;
  5198.       END;
  5199.     END;
  5200.     Ptr = POINTER TO Rec;
  5201.  
  5202.   VAR
  5203.     r: Rec;
  5204.     p: Ptr;
  5205.  
  5206.   PROCEDURE Foo(VAR r: Rec);
  5207.  
  5208.   END m2.
  5209.  
  5210.   (* Oberon-2 *) MODULE o2;
  5211.  
  5212.   IMPORT m2; (* import of a Modula-2 module *)
  5213.  
  5214.   VAR
  5215.     r: m2.Rec;  (* using the Modula-2 record type *)
  5216.     p: m2.Ptr;  (* using the Modula-2 pointer type *)
  5217.     x: POINTER TO m2.Rec;
  5218.  
  5219.   BEGIN
  5220.     NEW(p);     (* Modula-2 default ALLOCATE *)
  5221.     NEW(x);     (* Oberon-2 NEW *)
  5222.     m2.Foo(r);
  5223.     m2.Foo(p^);
  5224.     m2.Foo(x^);
  5225.   END o2.
  5226.  
  5227.  
  5228. ΓòÉΓòÉΓòÉ 10.1.3. Garbage collection ΓòÉΓòÉΓòÉ
  5229.  
  5230. It is important to remember that Modula-2 and Oberon-2 have different 
  5231. approaches to memory utilization. When a program contains both Modula-2 and 
  5232. Oberon-2 modules, garbage collection is used. See also Memory management. 
  5233.  
  5234.  
  5235. ΓòÉΓòÉΓòÉ 10.2. Direct language specification ΓòÉΓòÉΓòÉ
  5236.  
  5237. The compiler must know the language of implementation of any module to take 
  5238. into account different semantics of different languages and to generate a 
  5239. correct code. 
  5240.  
  5241. In some cases it is necessary for a procedure or data type to be implemented 
  5242. according to the rules of a language other than that of the whole module. XDS 
  5243. allows the language of a type or object to be specified explicitly. The direct 
  5244. language specification is allowed either if language extensions are allowed or 
  5245. if the module SYSTEM is imported. 
  5246.  
  5247. In a record, pointer, procedure type or procedure declaration, immediately 
  5248. following the keywords RECORD, POINTER or PROCEDURE, one may indicate the 
  5249. desired language (or the way in which this declaration is treated by the 
  5250. compiler) by [n], where n is a string or an integer constant expressionWe 
  5251. recommed to use strings, integer values are preserved for the backward 
  5252. compatibility.: 
  5253.  
  5254. The appearance of the following table is a known problem and will be improved 
  5255. in the final release. 
  5256.  
  5257. |l|c|c| Convention | String | Value 
  5258.  Oberon-2 | "Oberon" | 0 
  5259.  Modula-2 | "Modula" | 1 
  5260.  C | "C" | 2 
  5261.  Pascal | "Pascal" | 5 
  5262.  Win32 | "StdCall" | 7 
  5263.  
  5264. Example 
  5265.  
  5266. TYPE
  5267.   UntracedPtr = POINTER ["Modula"] TO Rec;
  5268.  
  5269. Here UntracedPtr is defined as the Modula-2 pointer, hence all variables of 
  5270. that type will not be traced by garbage collector. 
  5271.  
  5272. The direct language specification placed after the name of a field, constant, 
  5273. type or variable points out that the name of the object will be treated 
  5274. according to the rules of the specified language. 
  5275.  
  5276. TYPE
  5277.   Rec ["C"] = RECORD
  5278.     name ["C"]: INTEGER;
  5279.   END;
  5280.  
  5281. CONST pi ["C"] = 3.14159;
  5282.  
  5283. VAR buffer[]["C"]: POINTER TO INTEGER;
  5284.  
  5285. As in ISO Modula-2, an address may be specified for a variable, the empty 
  5286. brackets are required to set the language. 
  5287.  
  5288. A procedure name is treated according to the language of procedure decralation, 
  5289. i.e. in the following declaration: 
  5290.  
  5291. PROCEDURE ["C"] Foo;
  5292.  
  5293. both the procedure type and procedure name will be treated according to the C 
  5294. language rules. Note: if you are using C++ compiler, the Foo function should be 
  5295. declared with C name mangling style. See your C++ manuals for further 
  5296. information. 
  5297.  
  5298.  
  5299. ΓòÉΓòÉΓòÉ 10.3. Relaxation of compatibility rules ΓòÉΓòÉΓòÉ
  5300.  
  5301. The compiler performs all semantic checks for an object or type according to 
  5302. its language specifications. Any object declared as that of Modula-2 or 
  5303. Oberon-2 will satisfy Modula-2 or Oberon-2 compatibility rules respectively. 
  5304. The compiler uses relaxed compatibility rules for objects and types declared as 
  5305. "C", "Pascal" and "StdCall". 
  5306.  
  5307.  
  5308. ΓòÉΓòÉΓòÉ 10.3.1. Parameter compatibility ΓòÉΓòÉΓòÉ
  5309.  
  5310. If a formal parameter is of the type POINTER TO T, the actual parameter may be 
  5311. of any array type of T. In this case address of the first array element will be 
  5312. passed, as it is done in C. 
  5313. Example 
  5314.  
  5315. TYPE Str = POINTER TO CHAR;
  5316.  
  5317. PROCEDURE ["C"] Foo(s: Str); ... END Foo;
  5318.  
  5319. VAR
  5320.   s: Str;
  5321.   a: ARRAY [0..5] OF CHAR;
  5322.   p: POINTER TO ARRAY OF CHAR;
  5323.  
  5324.   Foo(s);   (* allowed - the same type *)
  5325.   Foo(a);   (* allowed for the "C" procedure *)
  5326.   Foo(p^);  (* allowed for the "C" procedure *)
  5327.  
  5328.  
  5329. ΓòÉΓòÉΓòÉ 10.3.2. Ignoring function result ΓòÉΓòÉΓòÉ
  5330.  
  5331. It is a standard practice in C programming to ignore a result of a function 
  5332. call. Some standard library functions are designed taking this practice into 
  5333. account. E.g. the string copy function gets a destination string as a variable 
  5334. parameter (in terms of Modula-2) and returns a pointer to it: 
  5335.  
  5336. extern char *strcpy(char *, const char *);
  5337.  
  5338. In many cases, the result of the strcpy function call is ignored. 
  5339.  
  5340. The XDS compilers allow one to ignore the results of functions, defined as "C", 
  5341. "Pascal" or "StdCall". Thus, the function strcpy defined in the string.def 
  5342. foreign definition module as 
  5343.  
  5344. PROCEDURE ["C"] strcpy(VAR d: ARRAY OF CHAR;
  5345.                            s: ARRAY OF CHAR): ADDRESS;
  5346.  
  5347. can be used as a proper procedure or as function procedure: 
  5348.  
  5349.   strcpy(d,s);
  5350.   ptr:=strcpy(d,s);
  5351.  
  5352.  
  5353. ΓòÉΓòÉΓòÉ 10.4. Interfacing to C ΓòÉΓòÉΓòÉ
  5354.  
  5355. A special attention was taken in XDS to provide a proper interface to other 
  5356. languages, primarily to the C language. The main goal is to provide an access 
  5357. to the existing software. Foreign definition modules provide definitions which 
  5358. allow the standard libraries to be directly accessed. 
  5359.  
  5360.  
  5361. ΓòÉΓòÉΓòÉ 10.4.1. Foreign definition module ΓòÉΓòÉΓòÉ
  5362.  
  5363. The direct language specification [n] can appear immediately after keywords 
  5364. DEFINITION MODULE (See Direct language specification). This has an effect that 
  5365. all objects defined in the module will be translated according to the 
  5366. correspondent language rules. Therefore, a direct language specification for 
  5367. each object is not necessary. 
  5368.  
  5369. Several options are often used in foreign definition modules. Note: options 
  5370. CSTDLIB and NOHEADER are meaningful for the translators to C only. 
  5371. Example 
  5372.  
  5373. <*+ M2EXTENSIONS *>
  5374. <*+ CSTDLIB *>      (* C standard library *)
  5375. <*+ NOHEADER *>     (* we already have header file *)
  5376. DEFINITION MODULE ["C"] string;
  5377.  
  5378. IMPORT SYSTEM;
  5379.  
  5380. PROCEDURE strlen(s: ARRAY OF CHAR): SYSTEM.size_t;
  5381. PROCEDURE strcmp(s1: ARRAY OF CHAR;
  5382.                  s2: ARRAY OF CHAR): SYSTEM.int;
  5383. END string.
  5384.  
  5385. If you are going to design your own foreign definition module, it will be 
  5386. usefull to take the following considerations into accout: 
  5387.  
  5388.      If you are developing an interface to the existing header file, use 
  5389.       NOHEADER option to disable the generation of header file. This option is 
  5390.       meaningful for the translators only. 
  5391.  
  5392.      If the header file is a standard header file, use the CSTDLIB option. 
  5393.       This option is meaningful for the translators only. 
  5394.  
  5395.      Use the special SYSTEM types int, unsigned, size_t and void for 
  5396.       corresponding C types. 
  5397.  
  5398.      A parameter of type T * should be replaced to the ARRAY OF T parameter, 
  5399.       if only arrays are passed to this parameter, otherwise use POINTER TO T. 
  5400.  
  5401.  Definition modules for the ANSI C libraries (stdio.def, string.def, etc) can 
  5402.  be used as tutorial examples. 
  5403.  
  5404.  
  5405. ΓòÉΓòÉΓòÉ 10.4.2. External procedures specification ΓòÉΓòÉΓòÉ
  5406.  
  5407. In some cases it may be desirable not to write a foreign definition module but 
  5408. to use some C functions directly. The XDS compilers allow a function to be 
  5409. declared as external. 
  5410.  
  5411. The declaration of an external procedure consists of a procedure header only. 
  5412. The procedure name in the header is prefixed by the symbol "/". 
  5413.  
  5414. PROCEDURE ["C"] / putchar(ch: SYSTEM.int): SYSTEM.int;
  5415.  
  5416.  
  5417. ΓòÉΓòÉΓòÉ 11. Libraries ΓòÉΓòÉΓòÉ
  5418.  
  5419. The following sets of libraries are provided with the compilers: 
  5420.  
  5421.      ISO standard Modula-2 libraries (ISO Standard Modula-2 libraries) 
  5422.  
  5423.      A subset of libraries defined in PIM (PIM standard libraries) 
  5424.  
  5425.      Utility libraries (Utility libraries) 
  5426.  
  5427.      A subset of Oberon-2 Oakwood standard libraries (Oberon-2 Oakwood 
  5428.       libraries) 
  5429.  
  5430.      Interface to Oberon-2 run-time support (The oberonRTS module) 
  5431.  
  5432.  All these libraries can be used with both Modula-2 and Oberon-2 compilers. 
  5433.  Some libraries are written in Oberon-2, others in Modula-2. If a program 
  5434.  consists of a mix of Oberon-2 and Modula-2 modules, two memory managers are in 
  5435.  use. In rare cases it can lead to the problem with memory allocation or 
  5436.  deallocation. A special care was taken to eliminate this problem (See Memory 
  5437.  management). 
  5438.  
  5439.  
  5440. ΓòÉΓòÉΓòÉ 11.1. ISO Standard Modula-2 libraries ΓòÉΓòÉΓòÉ
  5441.  
  5442. It is our aim to provide the full set of ISO Modula-2 libraries. However, not 
  5443. all libraries may be included in the current release (See Chapter 
  5444. Implementation limitations and restrictions). System libraries are described in 
  5445. Chapter XDS Modula-2. 
  5446.  
  5447. This section does not aim at full description of ISO libraries. All libraries 
  5448. are divided into groups. A brief description and few samples are provided for 
  5449. each group. For further information refer to the corresponding definition 
  5450. modules. 
  5451.  
  5452.  
  5453. ΓòÉΓòÉΓòÉ 11.1.1. Input/output library ΓòÉΓòÉΓòÉ
  5454.  
  5455. The IO library allows one to read and write the data streams over one or more 
  5456. channels. Channels are connected to the source of input data, or to destination 
  5457. of output data, known as devices. A set of devices can be extended. 
  5458.  
  5459. A group of modules is provided to operate on the default input and output 
  5460. channel (Reading and writing via default channels). Another group of modules 
  5461. provide facilities to operate on channels specified explicitly by a parameter 
  5462. (Reading and writing data). The device modules provide facilities to get a 
  5463. channel connected to a source (Device modules). The primitive 
  5464. device-independent operations are provided by the module IOChan; the module 
  5465. IOLink allows specialized device module to be implemented (See Low-level IO 
  5466. modules). 
  5467.  
  5468.  
  5469. ΓòÉΓòÉΓòÉ 11.1.2. Reading and writing via default channels ΓòÉΓòÉΓòÉ
  5470.  
  5471. The following modules provide procedures that operate via default input and 
  5472. output channels and do not take a parameter which identifies a channel: 
  5473.  
  5474. The appearance of the following table is a known problem and will be improved 
  5475. in the final release. 
  5476.  
  5477. lp7cm IOConsts | Types and constants for IO modules 
  5478.  SLongIO | LONGREAL numbers IO operations 
  5479.  SRawIO | Raw IO operations (no conversion or interpretation) 
  5480.  SRealIO | REAL numbers IO operations 
  5481.  SResultIO | Read results for the default input channel 
  5482.  STextIO | Character and string types IO operations 
  5483.  SWholeIO | Whole numbers IO operations 
  5484.  
  5485. The module STextIO resembles the well-known InOut library. The Hello, World 
  5486. program is implemented in the following example: 
  5487.  
  5488. MODULE Hello;
  5489.  
  5490. IMPORT  STextIO;
  5491.  
  5492. BEGIN
  5493.   STextIO.WriteString('Hello, World!');
  5494.   STextIO.WriteLn;
  5495. END Hello.
  5496.  
  5497. The modules SWholeIO, SRealIO, SLongIO provides facilities for the input and 
  5498. output of whole and real numbers in a decimal form using text operations on a 
  5499. channel. 
  5500.  
  5501. PROCEDURE Print(stage: CARDINAL; val: REAL);
  5502. BEGIN
  5503.   STextIO.WriteString("On stage");
  5504.   SWholeIO.WriteCard(stage,0);
  5505.   STextIO.WriteString(" the value is equal to ");
  5506.   SRealIO.WriteReal(val,15);
  5507.   STextIO.WriteLn;
  5508. END Print;
  5509.  
  5510. The module SIOResult allows one to determine whether the last input operation 
  5511. from a default input channel succeed. Text operations produce or consume data 
  5512. streams as a sequence of characters and line marks. The text input procedures 
  5513. (such as ReadString never remove a line mark from the input stream. The 
  5514. procedure SkipLine should be used to pass a line mark. 
  5515.  
  5516. The Copy procedure reads strings from the input channel and copies them to the 
  5517. output channel. 
  5518.  
  5519. PROCEDURE Copy;
  5520.   VAR s: ARRAY [0..63] OF CHAR;
  5521. BEGIN
  5522.   LOOP
  5523.     STextIO.ReadString(s);
  5524.     CASE SIOResult.ReadResult() OF
  5525.      |SIOResult.allRight:
  5526.         STextIO.WriteString(s);
  5527.      |SIOResult.endOfLine:
  5528.         STextIO.SkipLine;
  5529.         STextIO.WriteLn;
  5530.      |SIOResult.endOfInput:
  5531.         EXIT
  5532.     END;
  5533.   END;
  5534. END Copy;
  5535.  
  5536. No procedure is provided to get the result of a `write' operation. Device 
  5537. errors are reported by raising an exception (See module IOChan). 
  5538.  
  5539.  
  5540. ΓòÉΓòÉΓòÉ 11.1.3. Reading and writing data ΓòÉΓòÉΓòÉ
  5541.  
  5542. For all modules in this group a channel is specified by an actual parameter of 
  5543. the type IOChan.ChanId. 
  5544.  
  5545. The appearance of the following table is a known problem and will be improved 
  5546. in the final release. 
  5547.  
  5548. lp7cm IOResult | Read results for specified channels 
  5549.  LongIO | LONGREAL numbers IO operations 
  5550.  RawIO | Raw IO operations (no conversion or interpretation) 
  5551.  RealIO | REAL numbers IO operations 
  5552.  TextIO | Character and string types IO operations 
  5553.  WholeIO | Whole numbers IO operations 
  5554.  
  5555. The following procedure copies an input channel to an output channel byte by 
  5556. byte: 
  5557.  
  5558. PROCEDURE CopyChars(in,out: IOChan.ChanId);
  5559.   VAR ch: CHAR;
  5560. BEGIN
  5561.   LOOP
  5562.     TextIO.ReadChar(in,ch);
  5563.     CASE IOResult.ReadResult(in) OF
  5564.      |IOResult.allRight:
  5565.         TextIO.WriteChar(out,ch);
  5566.      |IOResult.endOfLine:
  5567.         TextIO.SkipLine(in);
  5568.         TextIO.WriteLn(out);
  5569.      |IOResult.endOfInput:
  5570.         EXIT
  5571.     END;
  5572.   END;
  5573. END CopyChars;
  5574.  
  5575.  
  5576. ΓòÉΓòÉΓòÉ 11.1.4. Device modules ΓòÉΓòÉΓòÉ
  5577.  
  5578. The device modules allows to get a channel connected to a stream, a file, 
  5579. program arguments and to default channels. 
  5580.  
  5581. The appearance of the following table is a known problem and will be improved 
  5582. in the final release. 
  5583.  
  5584. lp7cm ChanConsts | Common types and values for channel open requests and 
  5585. results 
  5586.  ProgramArgs | Access to program arguments 
  5587.  RndFile | Random access files 
  5588.  SeqFile | Rewindable sequential files 
  5589.  StdChans | Access to standard and default channels 
  5590.  StreamFile | Independent sequential data streams 
  5591.  
  5592. In the following example a channel connected to a rewindable file is opened: 
  5593.  
  5594. MODULE Example;
  5595.  
  5596. IMPORT  SeqFile, STextIO, TextIO;
  5597.  
  5598. CONST flags = SeqFile.text + SeqFile.old;
  5599.  
  5600. VAR
  5601.   cid: SeqFile.ChanId;
  5602.   res: SeqFile.OpenResults;
  5603.   i  : CARDINAL;
  5604.  
  5605. BEGIN
  5606.   SeqFile.OpenWrite(cid,"example.dat",flags,res);
  5607.   IF res = SeqFile.opened THEN
  5608.     FOR i:=0 TO 9 DO
  5609.       TextIO.WriteString(cid,"Hello");
  5610.       TextIO.WriteLn(cid);
  5611.     END;
  5612.     SeqFile.Close(cid);
  5613.   ELSE
  5614.     STextIO.WriteString("Open error");
  5615.     STextIO.WriteLn;
  5616.   END;
  5617. END Example.
  5618.  
  5619. The module StdChans allows one to get channels already open to sources and 
  5620. destinations of standard input, standard output and standard error output. 
  5621. Default channels initially corresponds to the standard channels, but their 
  5622. values may be changed to redirect input or output. 
  5623.  
  5624. PROCEDURE RedirectOutput(cid: StdChans.ChanId);
  5625. BEGIN
  5626. (* writing to the current default channel: *)
  5627.   STextIO.WriteString("Redirecting output...");
  5628.   STextIO.WriteLn;
  5629. (* redirecting output: *)
  5630.   StdChans.SetOutChan(cid);
  5631. END RedirectOutput;
  5632.  
  5633. After the call of RedirectOutput(cid) all subsequent output via modules 
  5634. STextIO, SWholeIO, etc will be written to the channel cid. To restore output 
  5635. call 
  5636.  
  5637.   StdChans.SetOutChan(StdChans.StdOutChan());
  5638.  
  5639. The module ProgramArgs provides a channel to access program's arguments. The 
  5640. following program prints all its arguments. 
  5641.  
  5642. MODULE Args;
  5643.  
  5644. IMPORT ProgramArgs, TextIO, STextIO;
  5645.  
  5646. VAR
  5647.   str: ARRAY [0..255] OF CHAR;
  5648.   cid: ProgramArgs.ChanId;
  5649.  
  5650. BEGIN
  5651.   cid:=ProgramArgs.ArgChan();
  5652.   WHILE ProgramArgs.IsArgPresent() DO
  5653.     TextIO.ReadToken(cid,str);
  5654.     (* Note: read result test is omitted *)
  5655.     STextIO.WriteString(str); STextIO.WriteLn;
  5656.   END;
  5657. END Args.
  5658.  
  5659.  
  5660. ΓòÉΓòÉΓòÉ 11.1.5. Low-level IO modules ΓòÉΓòÉΓòÉ
  5661.  
  5662. Two low-level modules are described in this section. The module IOChan defines 
  5663. the type ChanId that is used to identify channels and provides a set of 
  5664. procedures forming the channel's interface in a device-independent manner. 
  5665.  
  5666. The module IOLink provides facilities that allow one to define new device 
  5667. modules. Let us implement an encryption channel, i.e. a channel that encrypts 
  5668. all information that is written to it. To make the encryption 
  5669. device-independent we need a channel for input/output operations. 
  5670.  
  5671. In the following example a sketch of the encryption device module is shown. 
  5672.  
  5673. DEFINITION MODULE EncryptChan;
  5674.  
  5675. IMPORT IOChan, ChanConsts;
  5676.  
  5677. TYPE
  5678.   ChanId = IOChan.ChanId;
  5679.   OpenResults = ChanConsts.OpenResults;
  5680.  
  5681. PROCEDURE Connect(VAR cid: ChanId;
  5682.                        io: ChanId;
  5683.                   VAR res: OpenResults);
  5684. (* Attempts to open an encryption channel. All I/O
  5685.    operations will be made through "io" channel.
  5686. *)
  5687.  
  5688. PROCEDURE Close(VAR cid: ChanId);
  5689. (* Closes the channel. *)
  5690.  
  5691. END EncryptChan.
  5692.  
  5693. Values of the type DeviceId are used to identify device modules. By calling the 
  5694. procedure DeviceTablePtrValue, a device module can obtain a pointer to a device 
  5695. table for the channel. Each channel has it own copy of a device table. A device 
  5696. table contains a field in which the device module can store private data. In 
  5697. our example, the io channel will be stored in this field. The device table also 
  5698. serves as a method table (or virtual function table) in object-oriented 
  5699. languages. It contains the procedure variables for each device procedure. All 
  5700. fields are initialized by the call of MakeChan procedure. A device module has 
  5701. to assign its own device procedures to the fields of a device table. See the 
  5702. Connect procedure below. 
  5703.  
  5704. IMPLEMENTATION MODULE EncryptChan;
  5705.  
  5706. IMPORT IOChan, IOLink, ChanConsts, SYSTEM;
  5707.  
  5708. (* "did" is used to identify the channel's kind: *)
  5709. VAR did: IOLink.DeviceId;
  5710.  
  5711. PROCEDURE EncryptChar(from: SYSTEM.ADDRESS;
  5712.                          i: CARDINAL;
  5713.                     VAR ch: CHAR);
  5714. BEGIN
  5715.   ch:='a'; (* very simple encryption :-) *)
  5716. END EncryptChar;
  5717.  
  5718. PROCEDURE TextWrite(x: IOLink.DeviceTablePtr;
  5719.                  from: SYSTEM.ADDRESS;
  5720.                   len: CARDINAL);
  5721.   VAR i: CARDINAL;
  5722.      ch: CHAR;
  5723.     cid: IOChan.ChanId;
  5724. BEGIN
  5725.   (* get the channel id *)
  5726.   cid:=SYSTEM.CAST(IOChan.ChanId,x^.cd);
  5727.   FOR i:=0 TO len-1 DO
  5728.     (* encrypt i-th character *)
  5729.     EncryptChar(from,i,ch);
  5730.     (* write an encrypted character *)
  5731.     IOChan.TextWrite(cid,SYSTEM.ADR(ch),1);
  5732.   END;
  5733. END TextWrite;
  5734.  
  5735. PROCEDURE Connect(VAR cid: ChanId;
  5736.                        io: ChanId;
  5737.                   VAR res: OpenResults);
  5738.   VAR x: IOLink.DeviceTablePtr;
  5739. BEGIN
  5740.   IOLink.MakeChan(did,cid);
  5741.   IF cid = IOChan.InvalidChan() THEN
  5742.     res:=ChanConsts.outOfChans
  5743.   ELSE
  5744.     (* get a pointer to the device table *)
  5745.     x:=IOLink.DeviceTablePtrValue(cid,did,
  5746.                        IOChan.notAvailable,"");
  5747.     (* store the channel id *)
  5748.     x^.cd:=SYSTEM.CAST(SYSTEM.ADDRESS,io);
  5749.     x^.doTextWrite:=TextWrite;
  5750.     (* ... *)
  5751.   END;
  5752. END Connect;
  5753.  
  5754. PROCEDURE Close(VAR cid: ChanId);
  5755. BEGIN
  5756.   IOLink.UnMakeChan(did,cid);
  5757. END Close;
  5758.  
  5759. BEGIN
  5760.   IOLink.AllocateDeviceId(did);
  5761. END EncryptChan.
  5762.  
  5763. The module EncryptChan can be used as any standard device module. 
  5764.  
  5765.  
  5766. ΓòÉΓòÉΓòÉ 11.1.6. String conversions ΓòÉΓòÉΓòÉ
  5767.  
  5768. The string conversion library admits the conversion of the values of numeric 
  5769. data types to and from the character string representation. It contains the 
  5770. following modules: 
  5771.  
  5772. The appearance of the following table is a known problem and will be improved 
  5773. in the final release. 
  5774.  
  5775. lp8cm ConvTypes | Common types used in the string conversion modules 
  5776.  LongConv | Low-level LONGREAL/string conversions 
  5777.  LongStr | LONGREAL/string conversions 
  5778.  RealConv | Low-level REAL/string conversions 
  5779.  RealStr | REAL/string conversions 
  5780.  WholeConv | Low-level whole number/string conversions 
  5781.  WholeStr | Whole number/string conversions 
  5782.  
  5783. The module ConvTypes defines the enumeration type ConvResults. It also defines 
  5784. the types ScanClass and ScanState to use in the low-level conversion modules. 
  5785.  
  5786. The low-level conversion modules allow to control lexical scanning of character 
  5787. sequences. For example, the WholeConv module implements procedures ScanInt and 
  5788. ScanCard representing the start state for a finite state scanner for signed and 
  5789. unsigned whole numbers. In the following example the procedure ScanInt is used 
  5790. to locate a position of the first character in a string which is not a part of 
  5791. an integer. 
  5792.  
  5793. PROCEDURE SkipInt(str: ARRAY OF CHAR;
  5794.               VAR pos: CARDINAL);
  5795.   VAR len: CARDINAL;
  5796.     state: ConvTypes.ConvState;
  5797.     class: ConvTypes.ConvClass;
  5798. BEGIN
  5799.   pos:=0; len:=LENGTH(str);
  5800.   state:=WholeConv.ScanInt;
  5801.   WHILE pos < len DO
  5802.     state(str[pos],class,state);
  5803.     IF   (class = WholeConv.invalid)
  5804.       OR (class = WholeConv.terminator)
  5805.     THEN
  5806.       RETURN
  5807.     END;
  5808.     INC(pos);
  5809.   END;
  5810. END SkipInt;
  5811.  
  5812.  
  5813. ΓòÉΓòÉΓòÉ 11.1.7. Mathematical libraries ΓòÉΓòÉΓòÉ
  5814.  
  5815. The following modules constitute a mathematical library: 
  5816.  
  5817. The appearance of the following table is a known problem and will be improved 
  5818. in the final release. 
  5819.  
  5820. lp6.5cm ComplexMath | Mathematical functions for the type COMPLEX 
  5821.  LongComplexMath | Mathematical functions for the type LONGCOMPLEX 
  5822.  LongMath | Mathematical functions for the type LONGREAL 
  5823.  RealMath | Mathematical functions for the type REAL 
  5824.  
  5825.  
  5826. ΓòÉΓòÉΓòÉ 11.1.8. Processes and Semaphores ΓòÉΓòÉΓòÉ
  5827.  
  5828. The following modules concurrent algorithms to be expressed using processes: 
  5829.  
  5830. The appearance of the following table is a known problem and will be improved 
  5831. in the final release. 
  5832.  
  5833. ll Processes | Provides process creation and manipulation facilities. 
  5834.  Semaphores | Provides mutual exclusion facilities for use by processes. 
  5835.  
  5836. Example 
  5837.  
  5838. MODULE Test;
  5839.  
  5840. IMPORT Processes, Semaphores, STextIO;
  5841.  
  5842. VAR
  5843.   sig : Semaphores.SEMAPHORE;
  5844.   prs : Processes.ProcessId;
  5845.   main: Processes.ProcessId;
  5846.  
  5847. PROCEDURE Proc;
  5848. BEGIN
  5849.   STextIO.WriteString('Proc 1'); STextIO.WriteLn;
  5850.   Semaphores.Claim(sig); (* suspend until released *)
  5851.   STextIO.WriteString('Proc 2'); STextIO.WriteLn;
  5852.   Processes.StopMe;
  5853. END Proc;
  5854.  
  5855. BEGIN
  5856.   STextIO.WriteString('Main 1'); STextIO.WriteLn;
  5857.   Semaphores.Create(sig,0);
  5858.   main:=Processes.Me();
  5859.   Processes.Start(Proc,40000,Processes.UrgencyOf(main)+1,NIL,prs);
  5860.   STextIO.WriteString('Main 2'); STextIO.WriteLn;
  5861.   Semaphores.Release(sig);
  5862.   STextIO.WriteString('Main 3'); STextIO.WriteLn;
  5863.   Processes.StopMe;
  5864. END Test.
  5865.  
  5866.  
  5867. ΓòÉΓòÉΓòÉ 11.1.9. Other libraries ΓòÉΓòÉΓòÉ
  5868.  
  5869. In this section we list the ISO modules that do not belong to any of the above 
  5870. groups: 
  5871.  
  5872. The appearance of the following table is a known problem and will be improved 
  5873. in the final release. 
  5874.  
  5875. ll CharClass | provides predicates to test a value of a character type 
  5876.  Storage | Facilities for allocating and deallocating storage 
  5877.  Strings | Facilities for string manipulation 
  5878.  SysClock | Access to a system clock 
  5879.  
  5880.  
  5881. ΓòÉΓòÉΓòÉ 11.2. PIM standard libraries ΓòÉΓòÉΓòÉ
  5882.  
  5883. The following libraries defined in PIM are provided: 
  5884.  
  5885. The appearance of the following table is a known problem and will be improved 
  5886. in the final release. 
  5887.  
  5888. lp8cm InOut | general-purpose IO operations 
  5889.  LongInOut | LONGREAL numbers IO operations 
  5890.  MathLib0 | mathematical functions 
  5891.  RealInOut | REAL numbers IO operations 
  5892.  Terminal | computer's terminal IO operations 
  5893.  
  5894. The library LongInOut (similar to RealInOut is not described in PIM. All PIM 
  5895. libraries are implemented on a basis of the ISO library. Since PIM Storage 
  5896. library is not compatible with the corresponding ISO library, it is omitted. 
  5897.  
  5898.  
  5899. ΓòÉΓòÉΓòÉ 11.3. Utility libraries ΓòÉΓòÉΓòÉ
  5900.  
  5901. Starting from XDS v2.0 those modules that are portable between all versions of 
  5902. XDS on all platforms are included in the utility library. If you use ISO 
  5903. library, your program may be portable to any ISO compatible Modula-2 compiler. 
  5904. However, there are some essential omissions in the ISO library. The utility 
  5905. library is aimed at taking away some of those omissions. 
  5906.  
  5907. Some library modules are written in Oberon-2, others in Modula-2. In general 
  5908. any library can be used from both languages. However, do not forget that Oberon 
  5909. modules use implicit memory deallocation scheme and require garbage collection 
  5910. (See also Modula-2 and Oberon-2). 
  5911.  
  5912. The following modules of an utility library are provided (implementation 
  5913. language is pointed out in parentheses): 
  5914.  
  5915. The appearance of the following table is a known problem and will be improved 
  5916. in the final release. 
  5917.  
  5918. lll FileName | (M2) | Creating and parsing file names 
  5919.  FileSys | (M2) | Common file operations 
  5920.  FormOut | (M2) | Generic module for formatting output 
  5921.  FormStr | (M2) | Formatting output to strings 
  5922.  ProgEnv | (M2) | Access to program environment 
  5923.  DStrings | (O2) | Dynamic strings 
  5924.  FilePath | (O2) | File search operations 
  5925.  RegComp | (O2) | Regular expressions 
  5926.  
  5927.  
  5928. ΓòÉΓòÉΓòÉ 11.3.1. The FileName module ΓòÉΓòÉΓòÉ
  5929.  
  5930. The module provides operations for parsing and constructing file names. A file 
  5931. name consists of three parts: the directory, name and extension. 
  5932.  
  5933. All the procedures that construct a string value (Get, GetDir, GetName, GetExt, 
  5934. Convert, Create), have the property that if the length of the constructed 
  5935. string value exceeds the capacity of the variable parameter, a truncated value 
  5936. is assigned. If the length of the constructed string value is less than the 
  5937. capacity of the variable parameter, a string terminator is appended. 
  5938. Parsing file names 
  5939.  
  5940. The GetFormat procedure returns the position and length of file name parts. 
  5941.  
  5942.  
  5943. ΓòÉΓòÉΓòÉ 11.3.2. Format - File name format record ΓòÉΓòÉΓòÉ
  5944.  
  5945. TYPE
  5946.   Format = RECORD
  5947.     ok: BOOLEAN;
  5948.     (* directory position and length: *)
  5949.     dirPos, dirLen : CARDINAL;
  5950.     (* name position and length: *)
  5951.     namePos,nameLen: CARDINAL;
  5952.     (* extension position and length: *)
  5953.     extPos, extLen : CARDINAL;
  5954.   END;
  5955.  
  5956.  
  5957. ΓòÉΓòÉΓòÉ 11.3.3. GetFormat - Get file name format ΓòÉΓòÉΓòÉ
  5958.  
  5959. PROCEDURE GetFormat(str: ARRAY OF CHAR; VAR f: Format);
  5960.  
  5961. Returns the format of the string. The values of all fields are undefined if 
  5962. f.ok = FALSE. 
  5963.  
  5964. The following procedures return file name part(s). 
  5965.  
  5966. The appearance of the following table is a known problem and will be improved 
  5967. in the final release. 
  5968.  
  5969. |l@r| GetDir | Get directory 
  5970.  GetName | Get name of file 
  5971.  GetExt | Get extension 
  5972.  
  5973. PROCEDURE GetDir (fname: ARRAY OF CHAR;
  5974.                 VAR dir: ARRAY OF CHAR);
  5975. PROCEDURE GetName(fname: ARRAY OF CHAR;
  5976.                VAR name: ARRAY OF CHAR);
  5977. PROCEDURE GetExt (fname: ARRAY OF CHAR;
  5978.                 VAR ext: ARRAY OF CHAR);
  5979.  
  5980.  
  5981. ΓòÉΓòÉΓòÉ 11.3.4. Get - Get file name parts ΓòÉΓòÉΓòÉ
  5982.  
  5983. PROCEDURE Get(fname: ARRAY OF CHAR;
  5984.    VAR dir,name,ext: ARRAY OF CHAR);
  5985.  
  5986. File name construction 
  5987.  
  5988.  
  5989. ΓòÉΓòÉΓòÉ 11.3.5. Convert - Convert String to File Name ΓòÉΓòÉΓòÉ
  5990.  
  5991. PROCEDURE Convert(str: ARRAY OF CHAR;
  5992.             VAR fname: ARRAY OF CHAR);
  5993.  
  5994. Converts a string to a file name according to the conventions of the underlying 
  5995. file system. 
  5996.  
  5997.  
  5998. ΓòÉΓòÉΓòÉ 11.3.6. ConvertExt - Convert File Name Extension ΓòÉΓòÉΓòÉ
  5999.  
  6000. PROCEDURE ConvertExt(VAR ext: ARRAY OF CHAR);
  6001.  
  6002. Converts an extension according to the conventions of the underlying file 
  6003. system. 
  6004.  
  6005.  
  6006. ΓòÉΓòÉΓòÉ 11.3.7. Length - Calculate File Name Length ΓòÉΓòÉΓòÉ
  6007.  
  6008. PROCEDURE Length(dir,name,ext: CARDINAL): CARDINAL;
  6009.  
  6010. Using the lengths of the directory, name and extension returns an estimated 
  6011. file name length which is greater than or equal to the length of the name 
  6012. generated by the Create procedure call. 
  6013.  
  6014.  
  6015. ΓòÉΓòÉΓòÉ 11.3.8. Create - Create File Name ΓòÉΓòÉΓòÉ
  6016.  
  6017. PROCEDURE Create(dir,name,ext: ARRAY OF CHAR;
  6018.                     VAR fname: ARRAY OF CHAR);
  6019.  
  6020. Creates a file name from the parts. 
  6021. Example 
  6022.  
  6023. The following procedure can be used to change file name extension: 
  6024.  
  6025. PROCEDURE ChangeExt(VAR fname: ARRAY OF CHAR;
  6026.                        newext: ARRAY OF CHAR);
  6027.   CONST Len = 64;
  6028.   VAR
  6029.     dir,name: ARRAY [0..Len-1] OF CHAR;
  6030.     f: FileName.Format;
  6031.     len: CARDINAL;
  6032. BEGIN
  6033.   FileName.GetFormat(fname,f);
  6034.   IF NOT f.ok THEN Error("wrong format")
  6035.   ELSIF (f.dirLen > Len) OR (f.nameLen > Len) THEN
  6036.     Error("too long part");
  6037.   ELSE
  6038.     len:=FileName.Length(f.dirLen,f.nameLen,LENGTH(newext));
  6039.     IF len-1 > HIGH(fname) THEN
  6040.       Error("cannot create file name")
  6041.     ELSE
  6042.       FileName.Create(dir,name,newext,fname);
  6043.     END;
  6044.   END;
  6045. END ChangeExt;
  6046.  
  6047. When programming in Oberon-2 dynamic strings can be used to create strings of a 
  6048. required length: 
  6049.  
  6050. PROCEDURE ChangeExt(VAR fname: ARRAY OF CHAR;
  6051.                        newext: ARRAY OF CHAR);
  6052.   VAR
  6053.     dir,name: DStrings.String;
  6054.     f: FileName.Format;
  6055. BEGIN
  6056.   FileName.GetFormat(fname,f);
  6057.   IF NOT f.ok THEN Error("wrong format")
  6058.   ELSE
  6059.     NEW(dir,f.dirLen+1);
  6060.     NEW(name,f.nameLen+1);
  6061.     ...
  6062.     END;
  6063.   END;
  6064. END ChangeExt;
  6065.  
  6066.  
  6067. ΓòÉΓòÉΓòÉ 11.3.9. The FileSys module ΓòÉΓòÉΓòÉ
  6068.  
  6069. The module provides file common operations. 
  6070.  
  6071.  
  6072. ΓòÉΓòÉΓòÉ 11.3.10. Exists - Is File Exist ΓòÉΓòÉΓòÉ
  6073.  
  6074. PROCEDURE Exists(fname: ARRAY OF CHAR): BOOLEAN;
  6075.  
  6076. Returns TRUE, if file fname exists. 
  6077.  
  6078.  
  6079. ΓòÉΓòÉΓòÉ 11.3.11. ModifyTime - Return Modify Time ΓòÉΓòÉΓòÉ
  6080.  
  6081. PROCEDURE ModifyTime(fname: ARRAY OF CHAR;
  6082.                   VAR time: LONGCARD;
  6083.                 VAR exists: BOOLEAN);
  6084.  
  6085. Returns a file modification time; time is valid only if exists=TRUE. 
  6086.  
  6087.  
  6088. ΓòÉΓòÉΓòÉ 11.3.12. Rename - Rename File ΓòÉΓòÉΓòÉ
  6089.  
  6090. PROCEDURE Rename(fname,newname: ARRAY OF CHAR;
  6091.                       VAR done: BOOLEAN);
  6092.  
  6093. Renames the file fname to newname. 
  6094.  
  6095.  
  6096. ΓòÉΓòÉΓòÉ 11.3.13. Remove - Remove File ΓòÉΓòÉΓòÉ
  6097.  
  6098. PROCEDURE Remove(fname: ARRAY OF CHAR;
  6099.               VAR done: BOOLEAN);
  6100.  
  6101. Removes a file. 
  6102.  
  6103.  
  6104. ΓòÉΓòÉΓòÉ 11.3.14. The FormOut module ΓòÉΓòÉΓòÉ
  6105.  
  6106. The module implements a formatting output procedure which outputs its arguments 
  6107. according to the format parameter. The syntax of the format string is 
  6108. compatible with the corresponding parameter of the C procedure printf. Some 
  6109. useful format extensions are provided. 
  6110.  
  6111.  
  6112. ΓòÉΓòÉΓòÉ 11.3.15. writeProc - Write Procedure Type ΓòÉΓòÉΓòÉ
  6113.  
  6114. TYPE
  6115.   writeProc = PROCEDURE(
  6116.                 (*handle:*) SYSTEM.ADDRESS,
  6117.                 (*string:*) ARRAY OF CHAR,
  6118.                 (*length:*) INTEGER
  6119.               );
  6120.  
  6121.  
  6122. ΓòÉΓòÉΓòÉ 11.3.16. format - Formating Procedure ΓòÉΓòÉΓòÉ
  6123.  
  6124. PROCEDURE format(handle : SYSTEM.ADDRESS;
  6125.                  write  : writeProc;
  6126.                  fmt    : ARRAY OF CHAR;
  6127.                  linesep: CHAR;
  6128.                  args   : SYSTEM.ADDRESS;
  6129.                  size   : CARDINAL);
  6130.  
  6131. The procedure forms a string and outputs it via the write procedure parameter. 
  6132. The parameter handle is passed to the procedure write and provides a useful 
  6133. method to pass any information between the caller and the write procedure (e.g. 
  6134. output channel or something like it). The (args, size) pair denotes the address 
  6135. and size of the parameter block. The linesep parameter determines the line 
  6136. separator character sequence corresponding to "\n". Several standard values of 
  6137. the parameter are defined in the definition module: 
  6138.  
  6139. The appearance of the following table is a known problem and will be improved 
  6140. in the final release. 
  6141.  
  6142. ll default | default line separator for binary files 
  6143.  text | default line separator for text files 
  6144.  crlf | CR LF character sequence 
  6145.  
  6146. If the linesep is not equal to any of the values above, its value will be used 
  6147. as a line separator. 
  6148.  
  6149. The format string has the following syntax: 
  6150.  
  6151.   Format = { character | Specifier }.
  6152.   Specifier = "%" Modifier Width
  6153.             [ "." Precision [ "." Start ] ] Base.
  6154.   Modifier = "-" | "+" | "|" | "0" | "$" | "#".
  6155.   Width = [ unsigned number | "*" ].
  6156.   Precision = [ unsigned number | "*" ].
  6157.   Start = [ unsigned number | "*" ].
  6158.   Base = "d" | "i" | "x" | "X" | "o" | "{}"
  6159.        | "f" | "g" | "e".
  6160.  
  6161. The appearance of the following table is a known problem and will be improved 
  6162. in the final release. 
  6163.  
  6164. c|p8cm Modifier |Meaning 
  6165.  "-" | justifies a value to the left 
  6166.  "+" | prints a sign for numbers (even of a non-negative) 
  6167.  "|" | center value 
  6168.  "0" | fills a place for numbers with "0" characters (default - filling with 
  6169. spaces) 
  6170.  "$" | the same as "0" 
  6171.  "#" | prints a base character ("H" or "B") according to the base; for "o", "x" 
  6172. and "X" bases only. 
  6173.  
  6174. The appearance of the following table is a known problem and will be improved 
  6175. in the final release. 
  6176.  
  6177. c|p8.5cm Base |Meaning 
  6178.  "c" | prints a character 
  6179.  "d" | prints a value in a decimal form 
  6180.  "e" | prints a value in a floating-point form 
  6181.  "f" | prints a value in a fixed-point form 
  6182.  "g" | prints a value in a fixed-point or in floating-point form depending on 
  6183. the value 
  6184.  "i" | the same as "d" 
  6185.  "o" | prints a value in an octal form 
  6186.  "s" | prints a string 
  6187.  "x" | prints a value in a hexadecimal form, use letters "A".."F" 
  6188.  "X" | prints a value in a hexadecimal form, use letters "a".."f" 
  6189.  "{}" | prints a value as a bitset, e.g. {1,3..5} 
  6190.  
  6191. The procedure format converts the following pairs of symbols starting from the 
  6192. backslash (no convertion is done for strings printed using "%s" specifier): 
  6193.  
  6194. The appearance of the following table is a known problem and will be improved 
  6195. in the final release. 
  6196.  
  6197. c|p8cm Pair |Meaning 
  6198.  \n | prints the line separator according to the value of the linesep parameter 
  6199.  \r | prints CR (15C) 
  6200.  \f | prints FF (14C) 
  6201.  \t | prints TAB (11C) 
  6202.  \\ | prints the backslash 
  6203.  
  6204. Important notes: 
  6205.  
  6206.      neither the compiler nor the library checks the correspondence between 
  6207.       actual arguments and format specifications. However, unlike printf, all 
  6208.       specifiers whose arguments are not passed will be ignored. 
  6209.  
  6210.      the ISO conversion library (See String conversions) is used to output 
  6211.       numbers. 
  6212.  
  6213.      "*" in the width or precision position means that the corresponding 
  6214.       number is passed as current actual parameter. 
  6215.  
  6216.      for the "c" base the second number (precision) is a repetition factor. 
  6217.  
  6218.      for the "s" base the second number (precision) is the maximum number of 
  6219.       characters in a string to process. 
  6220.  
  6221.      for the "s" base the third number (start) specifies the start position in 
  6222.       a string to process. 
  6223.  
  6224.  
  6225. ΓòÉΓòÉΓòÉ 11.3.17. LineSeparator - Set Line Separator ΓòÉΓòÉΓòÉ
  6226.  
  6227. PROCEDURE LineSeparator(nl: ARRAY OF CHAR);
  6228.  
  6229. Sets the default line separator for binary files. The correct value for the 
  6230. given platform is set in the module initializaion. 
  6231.  
  6232.  
  6233. ΓòÉΓòÉΓòÉ 11.3.18. TextSeparator - Set Line Separator ΓòÉΓòÉΓòÉ
  6234.  
  6235. PROCEDURE TextSeparator(nl: ARRAY OF CHAR);
  6236.  
  6237. Sets the default line separator for text files. The correct value for the given 
  6238. platform is set in the module initializaion. 
  6239. Examples 
  6240.  
  6241. The following example shows the implementation of a procedure which produces a 
  6242. format output to an ISO channel. 
  6243.  
  6244. PROCEDURE ChanWrite(handle: SYSTEM.ADDRESS;
  6245.                     str: ARRAY OF CHAR;
  6246.                     len: INTEGER);
  6247.   VAR chan: IOChan.ChanId; pos: INTEGER;
  6248. BEGIN
  6249.   chan:=SYSTEM.CAST(IOChan.ChanId,handle);
  6250.   pos:=0;
  6251.   WHILE len > 0 DO
  6252.     IF str[pos] = ASCII.LF THEN IOChan.WriteLn
  6253.     ELSE IOChan.TextWrite(chan,SYSTEM.ADR(str[pos]),1)
  6254.     END;
  6255.     INC(pos); DEC(len);
  6256.   END;
  6257. END ChanWrite;
  6258.  
  6259. PROCEDURE Print(chan: IOChan.ChanId;
  6260.               format: ARRAY OF CHAR;
  6261.             SEQ args: SYSTEM.BYTE);
  6262. BEGIN
  6263.   FormOut.format(chan,ChanWrite,format,FormOut.text,
  6264.                  SYSTEM.ADR(args),SIZE(args));
  6265. END Print;
  6266.  
  6267. The procedure printf prints to the standard output channel: 
  6268.  
  6269. PROCEDURE printf(f: ARRAY OF CHAR; SEQ x: SYSTEM.BYTE);
  6270. BEGIN
  6271.   Print(StdChans.StdOutChan(),f,x);
  6272. END printf;
  6273.  
  6274. The procedure printf can be used in the conventional for C programmers way, 
  6275. e.g. the call 
  6276.  
  6277.   printf("%d! = %d\n",5,Factorial(5));
  6278.  
  6279. will produce the line Provided that the implementation of the procedure 
  6280. Factorial corresponds to its name. 
  6281.  
  6282.   5! = 120
  6283.  
  6284. Examples: 
  6285.  
  6286. The appearance of the following table is a known problem and will be improved 
  6287. in the final release. 
  6288.  
  6289. l|l Call | Output 
  6290.  printf("%5.3s","abcdef") |  abc 
  6291.  printf("%-5.3s","abcdef") | abc 
  6292.  printf("%|5.3s","abcdef") |  abc 
  6293.  printf("%..3s","abcdef") | def 
  6294.  printf("pos=%3d",13) | pos= 13 
  6295.  printf("%$3o",13) | 015 
  6296.  printf("%04X",33C) | 001B 
  6297.  printf("%{}",13) | {0,2..3} 
  6298.  
  6299.  
  6300. ΓòÉΓòÉΓòÉ 11.3.19. The FormStr module ΓòÉΓòÉΓòÉ
  6301.  
  6302. The appearance of the following table is a known problem and will be improved 
  6303. in the final release. 
  6304.  
  6305. |lp8cm|WARNING: | Language extensions are used in the interface of this module. 
  6306. All your modules importing this one may be non-portable to other compilers. 
  6307.  
  6308. A string is an array of characters of an arbitrary length. The procedures 
  6309. print, append and image guarantee the presence of the string terminator (0C) in 
  6310. the resulting string. See the module FormOut for information about the format 
  6311. syntax. 
  6312.  
  6313.  
  6314. ΓòÉΓòÉΓòÉ 11.3.20. print - Print to string ΓòÉΓòÉΓòÉ
  6315.  
  6316. PROCEDURE print(VAR str: ARRAY OF CHAR;
  6317.                  format: ARRAY OF CHAR;
  6318.                SEQ args: SYSTEM.BYTE);
  6319.  
  6320. Constructs a string specified by the pair (format,args) and places it into str. 
  6321.  
  6322.  
  6323. ΓòÉΓòÉΓòÉ 11.3.21. append - Append to the end of string ΓòÉΓòÉΓòÉ
  6324.  
  6325. PROCEDURE append( VAR str: ARRAY OF CHAR;
  6326.                    format: ARRAY OF CHAR;
  6327.                  SEQ args: SYSTEM.BYTE);
  6328.  
  6329. Appends a string specified by the pair (format,args) to the end of the string 
  6330. str. 
  6331.  
  6332.  
  6333. ΓòÉΓòÉΓòÉ 11.3.22. image - Print from the given position ΓòÉΓòÉΓòÉ
  6334.  
  6335. PROCEDURE image( VAR str: ARRAY OF CHAR;
  6336.                  VAR pos: LONGINT;
  6337.                   format: ARRAY OF CHAR;
  6338.                 SEQ args: SYSTEM.BYTE);
  6339.  
  6340. Places a string specified by the pair (format,args) in the string str starting 
  6341. from the position pos. After the procedure call, pos points to the 0C or to the 
  6342. position next to the end of the string. 
  6343.  
  6344.  
  6345. ΓòÉΓòÉΓòÉ 11.3.23. iscan - Read integer in Modula-2 format ΓòÉΓòÉΓòÉ
  6346.  
  6347. PROCEDURE iscan( VAR num: INTEGER;
  6348.                      str: ARRAY OF CHAR;
  6349.                  VAR pos: CARDINAL;
  6350.                 VAR done: BOOLEAN);
  6351.  
  6352. Reads the integer value from the string str starting from the position pos. 
  6353. After the procedure call we have: 
  6354.  
  6355. The appearance of the following table is a known problem and will be improved 
  6356. in the final release. 
  6357.  
  6358.  done  becomes TRUE, if the attempt was successful; 
  6359.  pos  is the index of the first character following the number; 
  6360.  num  is the read value when done=TRUE. 
  6361.  
  6362. The number may be represented in any form permissible in Modula-2. In case of 
  6363. an integer overflow done=FALSE. 
  6364.  
  6365.  
  6366. ΓòÉΓòÉΓòÉ 11.3.24. The ProgEnv module ΓòÉΓòÉΓòÉ
  6367.  
  6368. The module provides an access to the program environment. 
  6369.  
  6370.  
  6371. ΓòÉΓòÉΓòÉ 11.3.25. ArgNumber - Return the number of arguments ΓòÉΓòÉΓòÉ
  6372.  
  6373. PROCEDURE ArgNumber(): CARDINAL;
  6374.  
  6375. Returns the number of arguments (0 if there is no arguments). 
  6376.  
  6377.  
  6378. ΓòÉΓòÉΓòÉ 11.3.26. GetArg - Get argument ΓòÉΓòÉΓòÉ
  6379.  
  6380. PROCEDURE GetArg(n: CARDINAL; VAR arg: ARRAY OF CHAR);
  6381.  
  6382. Copies n-th argument to arg, or empty string if n >= ArgNumber(). 
  6383.  
  6384.  
  6385. ΓòÉΓòÉΓòÉ 11.3.27. ArgLength - Return length of argument ΓòÉΓòÉΓòÉ
  6386.  
  6387. PROCEDURE ArgLength(n: CARDINAL): CARDINAL;
  6388.  
  6389. Returns the length of the n-th argument (0 if n>=ArgNumber(). 
  6390.  
  6391.  
  6392. ΓòÉΓòÉΓòÉ 11.3.28. ProgramName - Get program name ΓòÉΓòÉΓòÉ
  6393.  
  6394. PROCEDURE ProgramName(VAR name: ARRAY OF CHAR);
  6395.  
  6396. Copies a program name to name. 
  6397.  
  6398.  
  6399. ΓòÉΓòÉΓòÉ 11.3.29. ProgramNameLength - Length of program name ΓòÉΓòÉΓòÉ
  6400.  
  6401. PROCEDURE ProgramNameLength(): CARDINAL;
  6402.  
  6403. Returns the length of the program name. 
  6404.  
  6405.  
  6406. ΓòÉΓòÉΓòÉ 11.3.30. String - Get environment string ΓòÉΓòÉΓòÉ
  6407.  
  6408. PROCEDURE String(name: ARRAY OF CHAR;
  6409.               VAR str: ARRAY OF CHAR);
  6410.  
  6411. Copies a value of the environment variable name to str (empty string if the 
  6412. variable is undefined). 
  6413.  
  6414.  
  6415. ΓòÉΓòÉΓòÉ 11.3.31. StringLength - Return environment string length ΓòÉΓòÉΓòÉ
  6416.  
  6417. PROCEDURE StringLength(name: ARRAY OF CHAR): CARDINAL;
  6418.  
  6419. Returns the length of the environment variable name (0 if the variable is 
  6420. undefined). 
  6421. Example 
  6422.  
  6423. The following procedure (in Oberon-2) prints all its arguments: 
  6424.  
  6425. PROCEDURE ShowArgs;
  6426.   VAR
  6427.     str: POINTER TO ARRAY OF CHAR;
  6428.     i,args: LONGINT;
  6429. BEGIN
  6430.   i:=0;
  6431.   args:=ProgEnv.ArgNumber();
  6432.   FOR i:=0 TO args-1 DO
  6433.     NEW(str,ProgEnv.ArgLength(i)+1);
  6434.     ProgEnv.GetArg(i,str^);
  6435.     STextIO.WriteString(str^); STextIO.WriteLn;
  6436.   END;
  6437. END ShowArgs;
  6438.  
  6439.  
  6440. ΓòÉΓòÉΓòÉ 11.3.32. The DStrings module ΓòÉΓòÉΓòÉ
  6441.  
  6442. The module DStrings (written in Oberon-2) defines a dynamic string type and 
  6443. provides some conventional operations. 
  6444.  
  6445.  
  6446. ΓòÉΓòÉΓòÉ 11.3.33. String - Dynamic String Type ΓòÉΓòÉΓòÉ
  6447.  
  6448. TYPE String* = POINTER TO ARRAY OF CHAR;
  6449.  
  6450.  
  6451. ΓòÉΓòÉΓòÉ 11.3.34. Assign - Create and Initialize String ΓòÉΓòÉΓòÉ
  6452.  
  6453. PROCEDURE Assign*(s: ARRAY OF CHAR; VAR d: String);
  6454.  
  6455. Allocates a new string and copies from s. The resulting string always contains 
  6456. the string terminator (0X). 
  6457.  
  6458.  
  6459. ΓòÉΓòÉΓòÉ 11.3.35. Append - Append to Dynamic String ΓòÉΓòÉΓòÉ
  6460.  
  6461. PROCEDURE Append*(s: ARRAY OF CHAR; VAR d: String);
  6462.  
  6463. Appends the string s, extending d if necessary. The resulting string always 
  6464. contains the string terminator (0X). 
  6465.  
  6466.  
  6467. ΓòÉΓòÉΓòÉ 11.3.36. The FilePath module ΓòÉΓòÉΓòÉ
  6468.  
  6469. The module (written in Oberon-2) provides file search facilities. In the 
  6470. following procedures path is a list of directories separated by semicolons, 
  6471. e.g. 
  6472.  
  6473.   .\SYM;C:\LIB\SYM;C:\XDS\LIB\SYM;.        (MS-DOS)
  6474.   ./sym;~/lib/sym;/usr/bin/xds/sym;.       (Unix)
  6475.  
  6476.  
  6477. ΓòÉΓòÉΓòÉ 11.3.37. IsSimpleName - Is just a File Name ΓòÉΓòÉΓòÉ
  6478.  
  6479. PROCEDURE IsSimpleName*(name: ARRAY OF CHAR): BOOLEAN;
  6480.  
  6481. Returns TRUE, if the name contains the file name only (does not contain 
  6482. directories). 
  6483.  
  6484.  
  6485. ΓòÉΓòÉΓòÉ 11.3.38. Lookup - Look up File ΓòÉΓòÉΓòÉ
  6486.  
  6487. PROCEDURE Lookup*(path,name: ARRAY OF CHAR;
  6488.                   VAR fname: DStrings.String;
  6489.                   VAR n: INTEGER);
  6490.  
  6491. Builds a filename using the search path. Returns: 
  6492.  
  6493. The appearance of the following table is a known problem and will be improved 
  6494. in the final release. 
  6495.  
  6496. ll n = -1 | name is not simple (fname := name) 
  6497.  n = 0 | file is not found (the first directory is used) 
  6498.  n > 0 | file is found in the n-th directory 
  6499.  
  6500.  
  6501. ΓòÉΓòÉΓòÉ 11.3.39. UseFirst - Use First Directory ΓòÉΓòÉΓòÉ
  6502.  
  6503. PROCEDURE UseFirst*(path,name: ARRAY OF CHAR;
  6504.                     VAR fname: DStrings.String);
  6505.  
  6506. Builds a filename using the first directory from the search path. 
  6507.  
  6508.  
  6509. ΓòÉΓòÉΓòÉ 11.3.40. The RegComp module ΓòÉΓòÉΓòÉ
  6510.  
  6511. This module (written in Oberon-2) implements a comparison of a string with 
  6512. regular expression. 
  6513. Regular expressions 
  6514.  
  6515. A regular expression is a string which contains certain special symbols. These 
  6516. are 
  6517.  
  6518.  *         denotes an arbitrary sequence of any character, possibly empty 
  6519.            (equivalent to {\000-\377} expression) 
  6520.  
  6521.  ?         denotes an arbitrary single character; (equivalent to the 
  6522.            [\000-\377] expression) 
  6523.  
  6524.  [characters] denotes one of the named characters 
  6525.  
  6526.  {characters} denotes an arbitrary sequence of the named characters; 
  6527.  
  6528.  \char '134nnn denotes an ASCII character with an octal code nnn where n is 
  6529.            [0-7]. 
  6530.  
  6531.  &         denotes the logical operation AND; 
  6532.  
  6533.  |         denotes the logical operation OR; 
  6534.  
  6535.  '136      denotes the logical operation NOT; 
  6536.  
  6537.  (..)      sets the priority of operations; 
  6538.  
  6539.  $digit    may be attached to *, ?, [], {} and (). In the later expressions, it 
  6540.            will represent the string of symbols comparable with the 
  6541.            subexpression preceding it. 
  6542.  
  6543.  A sequence of the form a-b used within either [] or {} brackets represents all 
  6544.  ASCII characters from a to b. 
  6545.  
  6546.  If you need to use any special symbols as an ordinary symbol, you should 
  6547.  precede it by the symbol \ which suppresses its interpretation. 
  6548.  Examples of regular expressions 
  6549.  
  6550.  {0-9A-F} defines the set of hexadecimal numbers 
  6551.  
  6552.  [a-zA-z_] defines a single small or capital letter or an underscore character. 
  6553.  
  6554.  (({0-9A-Fa-f})$1|({a-zA-Z_})$2))$3 corresponds to both hexadecimal numbers and 
  6555.  Modula-2 identifiers. The program could address a hexadecimal number by the $1 
  6556.  reference, identifier by the $2 reference and both of them by the $3 
  6557.  reference. 
  6558.  
  6559.  \\\$\{\}\[\]\*\? is equal to the string \${}[]*?. 
  6560.  Module description 
  6561.  
  6562.  
  6563. ΓòÉΓòÉΓòÉ 11.3.41. Expr - Regular expression ΓòÉΓòÉΓòÉ
  6564.  
  6565. TYPE
  6566.   Expr*    = POINTER TO ExprDesc;
  6567.   ExprDesc = RECORD END;
  6568.  
  6569.  
  6570. ΓòÉΓòÉΓòÉ 11.3.42. Compile - Compile regular expression ΓòÉΓòÉΓòÉ
  6571.  
  6572. PROCEDURE Compile*(expr: ARRAY OF CHAR;
  6573.                 VAR reg: Expr;
  6574.                 VAR res: LONGINT);
  6575.  
  6576. Compiles a regular expression to an internal form. 
  6577.  
  6578. The appearance of the following table is a known problem and will be improved 
  6579. in the final release. 
  6580.  
  6581. l|l Value of res | Meaning 
  6582.  res?0 | error in position ABS(res) 
  6583.  res > 0 | done 
  6584.  
  6585.  
  6586. ΓòÉΓòÉΓòÉ 11.3.43. Const - Is constant expression ΓòÉΓòÉΓòÉ
  6587.  
  6588. PROCEDURE Const*(re: Expr): BOOLEAN;
  6589.  
  6590. Returns TRUE, if an expression does not contain wildcards. 
  6591.  
  6592.  
  6593. ΓòÉΓòÉΓòÉ 11.3.44. Match - Compare string with expression ΓòÉΓòÉΓòÉ
  6594.  
  6595. PROCEDURE Match*(re: Expr;
  6596.                   s: ARRAY OF CHAR;
  6597.                 pos: LONGINT): BOOLEAN;
  6598.  
  6599. Returns TRUE, if the expression matches the string s starting from the position 
  6600. pos. 
  6601.  
  6602.  
  6603. ΓòÉΓòÉΓòÉ 11.3.45. Len - Length of substring ΓòÉΓòÉΓòÉ
  6604.  
  6605. PROCEDURE Len*(re: Expr; n: INTEGER): LONGINT;
  6606.  
  6607. Returns the length of the substring which corresponds to $n in the last call of 
  6608. the Match procedure with the parameter re. 
  6609.  
  6610.  
  6611. ΓòÉΓòÉΓòÉ 11.3.46. Pos - Position of substring ΓòÉΓòÉΓòÉ
  6612.  
  6613. PROCEDURE Pos*(re: Expr; n: INTEGER): LONGINT;
  6614.  
  6615. Returns the position of the substring which corresponds to $n in the last call 
  6616. of the Match procedure with the parameter re. 
  6617.  
  6618.  
  6619. ΓòÉΓòÉΓòÉ 11.3.47. Substitute - Substitute substrings ΓòÉΓòÉΓòÉ
  6620.  
  6621. PROCEDURE Substitute*(re: Expr;
  6622.                      s,m: ARRAY OF CHAR;
  6623.                    VAR d: ARRAY OF CHAR);
  6624.  
  6625. The substrings of s which match re are substituted instead of $digit into m and 
  6626. the result string is copied into d. 
  6627. Example 
  6628.  
  6629. After the following sequence of calls 
  6630.  
  6631.   Compile("{a-z}$1{0-9}$2",re,res);
  6632.   Substitute(re,"abcdef153","tail: $2 head: $1",dest);
  6633.  
  6634. the dest string will contain 
  6635.  
  6636.   "tail: 153 head: abcdef"
  6637.  
  6638.  
  6639. ΓòÉΓòÉΓòÉ 11.4. Oberon-2 Oakwood libraries ΓòÉΓòÉΓòÉ
  6640.  
  6641. The Oakwood Guidelines (See Chapter XDS Oberon-2) specifies a set of libraries 
  6642. that should be provided with all Oberon implementations. The current XDS 
  6643. release does not contain all libraries. The following libraries are currently 
  6644. available: 
  6645.  
  6646. The appearance of the following table is a known problem and will be improved 
  6647. in the final release. 
  6648.  
  6649. lp8cm In | input from a standard stream 
  6650.  MathR | mathematical functions for REAL 
  6651.  MathL | mathematical functions for LONGREAL 
  6652.  MathC | mathematical functions for COMPLEX 
  6653.  MathLC | mathematical functions for LONGCOMPLEX 
  6654.  Out | output to a standard stream 
  6655.  O2Strings | simple manipulations for strings 
  6656.  
  6657. The Math library is renamed to MathR, because it coincides with the ANSI C math 
  6658. library interface (See ???). The complex types and, hence, MathC and MathLC 
  6659. modules may be not available for other Oberon implementations (See also Oakwood 
  6660. numeric extensions). 
  6661.  
  6662. The Strings library is renamed to O2Strings, since it is not compatible with 
  6663. the correspondent ISO library. 
  6664.  
  6665.  
  6666. ΓòÉΓòÉΓòÉ 12. Run-time Support ΓòÉΓòÉΓòÉ
  6667.  
  6668. Some language features are implemented in a run-time support library, including 
  6669.  
  6670.      exceptions and finalization 
  6671.  
  6672.      coroutines 
  6673.  
  6674.      memory management 
  6675.  
  6676.      garbage collection 
  6677.  
  6678.      postmorten history 
  6679.  
  6680.  XDS provides an integrated Modula-2 and Oberon-2 run-time library, taking into 
  6681.  account the possibility that modules written in both languages are used in one 
  6682.  project. As a rule, if you do not use any feature the part of RTS that 
  6683.  implements this feature will not be added to your executable program. For 
  6684.  example, if you program is written in Modula-2 only, the Oberon part of RTS 
  6685.  (garbage collector, meta-language facilities) will not included. 
  6686.  
  6687.  The integrated memory manager is described in Memory management. The section 
  6688.  The oberonRTS module describes an interface to the Oberon-2 run-time support. 
  6689.  
  6690.  
  6691. ΓòÉΓòÉΓòÉ 12.1. Memory management ΓòÉΓòÉΓòÉ
  6692.  
  6693. The XDS integrated memory manager implements 
  6694.  
  6695.      default memory allocation and deallocation procedures for Modula-2 (See 
  6696.       the option STORAGE); 
  6697.  
  6698.      the memory allocation procedure for Oberon-2; 
  6699.  
  6700.      the system memory allocation procedure for Oberon-2 (See NEW and 
  6701.       DISPOSE); 
  6702.  
  6703.      the garbage collector. 
  6704.  
  6705.  The XDS provides the GCAUTO option and equations (GCTHRESHOLD and HEAPLIMIT) 
  6706.  to control the memory management. The option and equations should be set when 
  6707.  the top-level module of the program is compiled We recommend to set them into 
  6708.  the configuration or project file.. The XDS uses their values when generating 
  6709.  the call of RTS initialization. 
  6710.  
  6711.  The option GCAUTO allows the garbage collector to be called implicitly. If the 
  6712.  option is not set the garbage collector must be called explicitly (See The 
  6713.  oberonRTS module). The garbage collector is called implicitly by the memory 
  6714.  allocation procedure in the following cases: 
  6715.  
  6716.      a memory block of a required length cannot be allocated; 
  6717.  
  6718.      the amount of a busy memory exceeds the limit specified by the HEAPLIMIT 
  6719.       equation; 
  6720.  
  6721.      the amount of a busy memory exceeds the threshold specified by the 
  6722.       GCTHRESHOLD equation. 
  6723.  
  6724.  If the memory cannot be allocated after the call of the garbage collector, an 
  6725.  exception is raised, for a call from Oberon-2. 
  6726.  
  6727.  
  6728. ΓòÉΓòÉΓòÉ 12.2. History ΓòÉΓòÉΓòÉ
  6729.  
  6730. If the option GENHISTORYis set ON when compiling your program, the run-time 
  6731. system prints a stack of procedure calls on abnormal termination of your 
  6732. program, including 
  6733.  
  6734.      a file name 
  6735.  
  6736.      a line number 
  6737.  
  6738.      a program counter value 
  6739.  
  6740.      a procedure name (sometimes) 
  6741.  
  6742.  Note: all modules constituting your program should be compiled with the option 
  6743.  LINENO set ON. 
  6744.  
  6745.  To print the history, RTS scans the procedure stack of the coroutine that 
  6746.  caused an exception and tries to find procedure calls. This is not trivial 
  6747.  because of the highly optimized code generated by the compiler. For example, 
  6748.  not all procedures have a stack frame. 
  6749.  
  6750.  For each pointer to the code segment on the stack RTS checks the previous 
  6751.  command. If this command is a call command, it decides that this is a 
  6752.  procedure call. It is unlikely that RTS misses a procedure call, but it can be 
  6753.  cheated by something that looks like a procedure call. As a rule, it is caused 
  6754.  by uninitialized variables. 
  6755.  
  6756.  The first line of the history is always correct. For each line, except the 
  6757.  first, we recommend to check that the procedure shown in the previous line is 
  6758.  called from the given line. 
  6759.  
  6760.  The following example shows a sketch of the program and the procedure stack: 
  6761.  
  6762.   PROCEDURE P1;
  6763.     (* uninitialized variable: *)
  6764.     VAR x: ARRAY [0..50] OF INTEGER;
  6765.   BEGIN
  6766.     i:=i DIV j;   (* line 50 *)
  6767.   END P1;
  6768.  
  6769.   PROCEDURE P2;
  6770.   BEGIN
  6771.     i:=i DIV j;   (* line 100 *)
  6772.   END P2;
  6773.  
  6774.   PROCEDURE P3;
  6775.   BEGIN
  6776.     P1;           (* line 150 *)
  6777.   END P2;
  6778.  
  6779.   #RTS: No exception handler #6: zero or negative divisor
  6780.   ------------------------------------------------------------
  6781.   Source file                        LINE  OFFSET  PROCEDURE
  6782.   ------------------------------------------------------------
  6783.   "test.mod"                           50 000000DE
  6784.   "test.mod"                          100 0000024C
  6785.   "test.mod"                          150 0000051D
  6786.  
  6787.  It is obvious from the source text that the procedure P1 cannot be called from 
  6788.  P2. The second line is superfluous. 
  6789.  
  6790.  
  6791. ΓòÉΓòÉΓòÉ 12.3. The oberonRTS module ΓòÉΓòÉΓòÉ
  6792.  
  6793. The run time support (RTS) is an integral part of the Oberon-2 language 
  6794. implementation. It includes the command activation, memory allocation, garbage 
  6795. collection and meta-language facilities. The module oberonRTS provides an 
  6796. interface to these features. 
  6797.  
  6798.  
  6799. ΓòÉΓòÉΓòÉ 12.3.1. Types and variables ΓòÉΓòÉΓòÉ
  6800.  
  6801. The appearance of the following table is a known problem and will be improved 
  6802. in the final release. 
  6803.  
  6804. |l@r| Module | run-time data structure for a module 
  6805.  Type | run-time data structure for a data type 
  6806.  Command | parameterless procedure 
  6807.  
  6808. TYPE
  6809.   Module;
  6810.   Type;
  6811.   Command = PROC;
  6812.   CARDINAL = SYSTEM.CARD32;
  6813.  
  6814. The appearance of the following table is a known problem and will be improved 
  6815. in the final release. 
  6816.  
  6817. |l@r| nullModule | NIL of Module Type 
  6818.  nullType | NIL of Type Type 
  6819.  
  6820. VAR
  6821.   nullModule: Module;
  6822.   nullType: Type;
  6823.  
  6824.  
  6825. ΓòÉΓòÉΓòÉ 12.3.2. Garbage collection ΓòÉΓòÉΓòÉ
  6826.  
  6827.  
  6828. ΓòÉΓòÉΓòÉ 12.3.3. Collect - Garbage Collector ΓòÉΓòÉΓòÉ
  6829.  
  6830. PROCEDURE Collect;
  6831.  
  6832. Invokes the garbage collector. 
  6833.  
  6834.  
  6835. ΓòÉΓòÉΓòÉ 12.3.4. GetInfo - Get Memory Information ΓòÉΓòÉΓòÉ
  6836.  
  6837. PROCEDURE GetInfo(VAR objects, busymem: CARDINAL);
  6838.  
  6839. Returns the number of allocated objects and the total size of the allocated 
  6840. memory. 
  6841.  
  6842.  
  6843. ΓòÉΓòÉΓòÉ 12.3.5. Object finalization ΓòÉΓòÉΓòÉ
  6844.  
  6845. A system with garbage collection has some specific features. Its main 
  6846. difference from other systems is that deallocation of any system resource must 
  6847. be postponed until garbage collection. For example, let some data structure 
  6848. contain descriptors of open files. To close a file (i.e. to destroy its 
  6849. descriptor), one needs to know that there are no references to this file. This 
  6850. information becomes known only in the course of garbage collection. The same 
  6851. argument also holds for other kinds of resources. 
  6852.  
  6853. One immediate implication is that there must be some finalization mechanism: 
  6854. the ability to perform certain operations with an object when there are no more 
  6855. references to it. 
  6856.  
  6857. The XDS allows one to attach a finalization procedure to any object. 
  6858.  
  6859.  
  6860. ΓòÉΓòÉΓòÉ 12.3.6. Finalizer - Type of a finalization procedure ΓòÉΓòÉΓòÉ
  6861.  
  6862. TYPE Finalizer = PROCEDURE (SYSTEM.ADDRESS);
  6863.  
  6864.  
  6865. ΓòÉΓòÉΓòÉ 12.3.7. InstallFinalizer - Set a finalizer to an object ΓòÉΓòÉΓòÉ
  6866.  
  6867. PROCEDURE InstallFinalizer(f: Finalizer; obj: SYSTEM.ADDRESS);
  6868.  
  6869. The procedure sets a finalization procedure "f" for object "obj". This 
  6870. procedure is called when the object becomes unreachable. Note: a finalizer is 
  6871. called on GC stack (stack size is limited); 
  6872. Example 
  6873.  
  6874. TYPE
  6875.   Obj = POINTER TO ObjDesc;
  6876.   ObjDesc = RECORD
  6877.     file: File; (* file handler *)
  6878.   END;
  6879.  
  6880. PROCEDURE Final(x: SYSTEM.ADDRESS);
  6881.   VAR o: Obj;
  6882. BEGIN
  6883.   o:=SYSTEM.CAST(Obj,x);
  6884.   IF o.file # NIL THEN Close(file) END;
  6885. END Final;
  6886.  
  6887. PROCEDURE Create(): Obj;
  6888.   VAR o: Obj;
  6889. BEGIN
  6890.   NEW(o);
  6891.   o.file:=NIL;
  6892.   oberonRTS.InstallFinalizer(Final,o);
  6893.   TryOpen(o.file);
  6894. END Create;
  6895.  
  6896.  
  6897. ΓòÉΓòÉΓòÉ 12.3.8. Meta-language facilities ΓòÉΓòÉΓòÉ
  6898.  
  6899. The meta-programming operations allow one to retrieve the type of an object, to 
  6900. create an object of a given type, to get the name of a type and a type by its 
  6901. name, etc. 
  6902.  
  6903.  
  6904. ΓòÉΓòÉΓòÉ 12.3.9. Search - Search a Module by its Name ΓòÉΓòÉΓòÉ
  6905.  
  6906. PROCEDURE Search(name: ARRAY OF CHAR): Module;
  6907.  
  6908. Returns a module by its name or nullModule. 
  6909.  
  6910.  
  6911. ΓòÉΓòÉΓòÉ 12.3.10. NameOfModule - Name of Module ΓòÉΓòÉΓòÉ
  6912.  
  6913. PROCEDURE NameOfModule(m: Module;
  6914.                 VAR name: ARRAY OF CHAR);
  6915.  
  6916. Returns the name of the module. 
  6917.  
  6918.  
  6919. ΓòÉΓòÉΓòÉ 12.3.11. ThisCommand - Get Command by its Name ΓòÉΓòÉΓòÉ
  6920.  
  6921. PROCEDURE ThisCommand(m: Module;
  6922.                    name: ARRAY OF CHAR;
  6923.                      ): Command;
  6924.  
  6925. Returns a command (parameterless procedure) named name in the module m or NIL, 
  6926. if such a command does not exist. 
  6927.  
  6928.  
  6929. ΓòÉΓòÉΓòÉ 12.3.12. ThisType - Get Type by its Name ΓòÉΓòÉΓòÉ
  6930.  
  6931. PROCEDURE ThisType(m: Module;
  6932.                 name: ARRAY OF CHAR): Type;
  6933.  
  6934. Returns a type declared in the module m or nullType, if such type does not 
  6935. exist. 
  6936.  
  6937.  
  6938. ΓòÉΓòÉΓòÉ 12.3.13. SizeOf - Size of Type ΓòÉΓòÉΓòÉ
  6939.  
  6940. PROCEDURE SizeOf(t: Type): INTEGER;
  6941.  
  6942. Returns the size (in bytes) of an object of the type t. 
  6943.  
  6944.  
  6945. ΓòÉΓòÉΓòÉ 12.3.14. BaseOf - Base of Type ΓòÉΓòÉΓòÉ
  6946.  
  6947. PROCEDURE BaseOf(t: Type; level: INTEGER): Type;
  6948.  
  6949. Returns the level-th base type of t. 
  6950.  
  6951.  
  6952. ΓòÉΓòÉΓòÉ 12.3.15. LevelOf - Level of Type Extension ΓòÉΓòÉΓòÉ
  6953.  
  6954. PROCEDURE LevelOf(t: Type): INTEGER;
  6955.  
  6956. Returns a level of the type extension. 
  6957.  
  6958.  
  6959. ΓòÉΓòÉΓòÉ 12.3.16. ModuleOf - Module of Type ΓòÉΓòÉΓòÉ
  6960.  
  6961. PROCEDURE ModuleOf(t: Type): Module;
  6962.  
  6963. Returns the module in which the type t was declared. 
  6964.  
  6965.  
  6966. ΓòÉΓòÉΓòÉ 12.3.17. NameOfType - Name of Type ΓòÉΓòÉΓòÉ
  6967.  
  6968. PROCEDURE NameOfType(t: Type; VAR name: ARRAY OF CHAR);
  6969.  
  6970. Returns the name of the record type. 
  6971.  
  6972.  
  6973. ΓòÉΓòÉΓòÉ 12.3.18. TypeOf - Type of Object ΓòÉΓòÉΓòÉ
  6974.  
  6975. PROCEDURE TypeOf(obj: SYSTEM.ADDRESS): Type;
  6976.  
  6977. Returns the type of the object. 
  6978.  
  6979.  
  6980. ΓòÉΓòÉΓòÉ 12.3.19. New Object - Create Object ΓòÉΓòÉΓòÉ
  6981.  
  6982. PROCEDURE NewObj(type: Type): SYSTEM.ADDRESS;
  6983.  
  6984. Creates a new object of the type t. 
  6985.  
  6986.  
  6987. ΓòÉΓòÉΓòÉ 12.3.20. Module iterators ΓòÉΓòÉΓòÉ
  6988.  
  6989. The module provides iterators which allow one to iterate all loaded modules, 
  6990. all commands and all object types (i.e., exported record types). 
  6991.  
  6992.  
  6993. ΓòÉΓòÉΓòÉ 12.3.21. NameIterator - Iterator Type ΓòÉΓòÉΓòÉ
  6994.  
  6995. TYPE
  6996.   NameIterator = PROCEDURE (
  6997.                    (*context:*) SYSTEM.ADDRESS,
  6998.                    (*name:*) ARRAY OF CHAR
  6999.                  ): BOOLEAN;
  7000.  
  7001. The NameIterator is called by an iterator on each iterated item. An iterator 
  7002. passes the name of the item along with the so-called context word. This allows 
  7003. some context information to be passed to the user-defined procedure (e.g., the 
  7004. file handler). If the iterated procedure returns FALSE, the iteration is broken 
  7005. off. 
  7006.  
  7007.  
  7008. ΓòÉΓòÉΓòÉ 12.3.22. IterModules - Iterate all Modules ΓòÉΓòÉΓòÉ
  7009.  
  7010. PROCEDURE IterModules(context: SYSTEM.ADDRESS;
  7011.                          iter: NameIterator);
  7012.  
  7013. The procedure iterates all Oberon-2 modules. 
  7014.  
  7015.  
  7016. ΓòÉΓòÉΓòÉ 12.3.23. IterCommands - Iterate Commands ΓòÉΓòÉΓòÉ
  7017.  
  7018. PROCEDURE IterCommands(mod: Module;
  7019.                    context: SYSTEM.ADDRESS;
  7020.                       iter: NameIterator);
  7021.  
  7022. Iterates all commands implemented in the module mod. 
  7023.  
  7024.  
  7025. ΓòÉΓòÉΓòÉ 12.3.24. IterTypes - Iterate Record Types ΓòÉΓòÉΓòÉ
  7026.  
  7027. PROCEDURE IterTypes(mod: Module;
  7028.                 context: SYSTEM.WORD;
  7029.                    iter: NameIterator);
  7030.  
  7031. Iterates all record types declared in the module mod. 
  7032.  
  7033.  
  7034. ΓòÉΓòÉΓòÉ 13. Configuring XDS for a C Compiler ΓòÉΓòÉΓòÉ
  7035.  
  7036. XDS allows C functions and libraries to be used in your projects. Different C 
  7037. compilers have different naming and calling conventions. You have to specify 
  7038. your C compiler in XDS environment using the CC equation. The equation forces 
  7039. XDS to call all C functions in a way compatible with the specified C compiler. 
  7040. Also the compiler sets the default values of additional configuration options 
  7041. according to the value of the equation. See Additional configuration options. 
  7042.  
  7043. For Windows NT and Windows 95 XDS supports the MSVC++ and Watcom compilers. The 
  7044. corresponding values of the CC equations are MSVC and WATCOM, written in any 
  7045. case. If the equation does not set, the compiler will assume WATCOM by default. 
  7046. To configure XDS append the line 
  7047.  
  7048. -cc=Watcom
  7049.  
  7050. or 
  7051.  
  7052. -cc=MSVC
  7053.  
  7054. to your configuration file. 
  7055.  
  7056. See samples.txt from XDS on-line documentation for more information. 
  7057.  
  7058.  
  7059. ΓòÉΓòÉΓòÉ 13.1. Possible problems ΓòÉΓòÉΓòÉ
  7060.  
  7061. To use a C function or a data type from Modula-2 or Oberon-2 one have to 
  7062. express its type in one of these languages. Usually it is done in a foreign 
  7063. definition module (See Interfacing to C). The current version of XDS does not 
  7064. support all calling conventions, thats why using of some functions is 
  7065. impossible, namely: 
  7066.  
  7067.      functions with parameter of a structured type, passed by value, e.g.: 
  7068.  
  7069.             void foo(struct MyStruct s)
  7070.  
  7071.      functions that return structured types, e.g.: 
  7072.  
  7073.             struct MyStruct foo(void)
  7074.  
  7075.      C functions with Pascal calling convention that return the real type. 
  7076.  
  7077.      functions that are compiled with non-stack calling conventions. Note: 
  7078.       stack calling conventions shall be set for Watcom using "-3s", "-4s" or 
  7079.       "-5s" option. 
  7080.  
  7081.  XDS does not support the use of data structures with non-standard alignment. 
  7082.  If the ALIGNMENT option is off, use the option "-zp1" for Watcom C and "-Zp1" 
  7083.  for MSVC. Otherwise, use "-zp4" (Watcom) and "-Zp4" (MSVC). 
  7084.  
  7085.  Both Modula-2 and C/C++ have exception handling and finalization facilities. 
  7086.  Unpredictable results may occur if you try to use facilities from both 
  7087.  languages in one program. 
  7088.  
  7089.  
  7090. ΓòÉΓòÉΓòÉ 13.2. Using unsupported compiler ΓòÉΓòÉΓòÉ
  7091.  
  7092. XDS does not support all available C compilers. You can use additional 
  7093. configuration options (See Additional configuration options) to adapt XDS to 
  7094. your compiler. The DEFLIBS option should be switched off in that case. 
  7095.  
  7096. It may be necessary to make some changes in the run-time support for the 
  7097. particular extender. It can be done in terms of our support program. 
  7098.  
  7099.  
  7100. ΓòÉΓòÉΓòÉ 13.3. Additional configuration options ΓòÉΓòÉΓòÉ
  7101.  
  7102. Additional configuration options can be used to adapt XDS to unsupported C 
  7103. compiler. We recommend to use these options with care. 
  7104.  
  7105.  GENCPREF 
  7106.  
  7107.            If the option is ON, the compiler appends underscore as a prefix for 
  7108.            all names in object files. 
  7109.  
  7110.  ONECODESEG 
  7111.  
  7112.            If the option is ON, the compiler produces only one code segment 
  7113.            which contains all code of a module, otherwise it generates separate 
  7114.            code segment for each procedure. 
  7115.  
  7116.  The table below shows the default values of these options for the supported C 
  7117.  compilers: 
  7118.  
  7119.  The appearance of the following table is a known problem and will be improved 
  7120.  in the final release. 
  7121.  
  7122.  |l|c|c|c|c| Option | WATCOM | MSVC 
  7123.   comment DS_NEQ_SS | ? | ? 
  7124.   GENCPREF | OFF | ON 
  7125.   ONECODESEG | OFF | ON 
  7126.  
  7127.  
  7128. ΓòÉΓòÉΓòÉ 14. Low-level Programming ΓòÉΓòÉΓòÉ
  7129.  
  7130.  
  7131. ΓòÉΓòÉΓòÉ 14.1. Data representation ΓòÉΓòÉΓòÉ
  7132.  
  7133. The internal representation of values of Modula-2 and Oberon-2 basic types is 
  7134. described in the tables ??? and ???. In the table Data representation a 
  7135. representation of system types is described. 
  7136.  
  7137. The appearance of the following table is a known problem and will be improved 
  7138. in the final release. 
  7139.  
  7140. |l|c|l| Modula-2 type | Bits |Representation 
  7141.  SHORTINT | 8 | signed 
  7142.  INTEGER | 16/32 | signed (See Modula-2 INTEGER and CARDINAL types) 
  7143.  LONGINT | 32 | signed 
  7144.  SHORTCARD | 8 | unsigned 
  7145.  CARDINAL | 16/32 | unsigned (See Modula-2 INTEGER and CARDINAL types) 
  7146.  LONGCARD | 32 | unsigned 
  7147.  CHAR | 8 | unsigned 
  7148.  BOOLEAN | 8/32 | unsigned (See Modula-2 BOOLEAN type) 
  7149.  | | 0 for FALSE, 1 for TRUE 
  7150.  subranges | | according to the base type 
  7151.  REAL | 32 | 80387 single-precision data format 
  7152.  LONGREAL | 64 | 80387 double-precision data format 
  7153.  
  7154. Representation of Modula-2 basic types 
  7155.  
  7156. The appearance of the following table is a known problem and will be improved 
  7157. in the final release. 
  7158.  
  7159. |l|c|l| Oberon-2 type | Bits |Representation 
  7160.  SHORTINT | 8 | signed 
  7161.  INTEGER | 16 | signed 
  7162.  LONGINT | 32 | signed 
  7163.  CHAR | 8 | unsigned 
  7164.  BOOLEAN | 8 | unsigned byte 
  7165.  | | 0 for FALSE, 1 for TRUE 
  7166.  REAL | 32 | 80387 single-precision data format 
  7167.  LONGREAL | 64 | 80387 double-precision data format 
  7168.  SET | 32 | unsigned 
  7169.  
  7170. Representation of Oberon-2 basic types 
  7171.  
  7172. The appearance of the following table is a known problem and will be improved 
  7173. in the final release. 
  7174.  
  7175. |l|c|l| System type | Bits |Representation 
  7176.  ADDRESS | 32 | unsigned 
  7177.  BOOL8 | 8 | unsigned 
  7178.  BOOL32 | 32 | unsigned 
  7179.  BYTE | 8 | unsigned 
  7180.  CARD8 | 8 | unsigned 
  7181.  CARD16 | 16 | unsigned 
  7182.  CARD32 | 32 | unsigned 
  7183.  INT8 | 8 | signed 
  7184.  INT16 | 16 | signed 
  7185.  INT32 | 32 | signed 
  7186.  LOC | 8 | unsigned 
  7187.  WORD | 32 | ARRAY [0..3] OF LOC 
  7188.  
  7189. Representation of SYSTEM types 
  7190.  
  7191.  
  7192. ΓòÉΓòÉΓòÉ 14.1.1. Modula-2 INTEGER and CARDINAL types ΓòÉΓòÉΓòÉ
  7193.  
  7194. If the option M2BASE16 is OFF, INTEGER and CARDINAL types are represented as 
  7195. 32-bit values, otherwise as 16-bit values. 
  7196.  
  7197.  
  7198. ΓòÉΓòÉΓòÉ 14.1.2. Modula-2 BOOLEAN type ΓòÉΓòÉΓòÉ
  7199.  
  7200. If the option M2UNPACKTYPES is OFF, boolean type is represented as unsigned 
  7201. 1-byte value, otherwise as unsigned 32-bit value. 
  7202.  
  7203.  
  7204. ΓòÉΓòÉΓòÉ 14.1.3. Modula-2 enumeration types ΓòÉΓòÉΓòÉ
  7205.  
  7206. If the option M2UNPACKTYPES is OFF, Modula-2 enumeration types of no more than 
  7207. 256 and 65536 elements are represented as unsigned 1 or 2-byte values 
  7208. respectively. Otherwise, enumerations are represented as 4-byte values. 
  7209.  
  7210.  
  7211. ΓòÉΓòÉΓòÉ 14.1.4. Modula-2 set types ΓòÉΓòÉΓòÉ
  7212.  
  7213. If the option M2UNPACKTYPES is OFF, Modula-2 sets of no more than 8, 16 and 32 
  7214. elements are represented as unsigned 1, 2 or 4-byte values respectively. 
  7215. Otherwise, sets of no more than 32 elements are represented as 4-byte values. 
  7216.  
  7217. If the option M2BASE16 is OFF, BITSET type is represented as unsigned 32-bit 
  7218. values, otherwise as 16-bit values. 
  7219.  
  7220.  
  7221. ΓòÉΓòÉΓòÉ 14.1.5. Pointer, address and opaque types ΓòÉΓòÉΓòÉ
  7222.  
  7223. Address types are represented as 32-bit (4-byte) unsigned values containing the 
  7224. byte offset in the task data segment. The address arithmetic is implemented as 
  7225. 32-bit unsigned arithmetic without overflow checks. 
  7226.  
  7227.  
  7228. ΓòÉΓòÉΓòÉ 14.1.6. Procedure types ΓòÉΓòÉΓòÉ
  7229.  
  7230. Procedure types are represented by the 32-bit (4-byte) address of the 
  7231. procedure's entry point in the task code segment. 
  7232.  
  7233.  
  7234. ΓòÉΓòÉΓòÉ 14.1.7. Record types ΓòÉΓòÉΓòÉ
  7235.  
  7236. Records are represented by a continuous memory segment containing all record 
  7237. components (fields) in a representation corresponding to their type. If the 
  7238. option ALIGNMENT is ON, the compiler aligns each field according to its size. 
  7239. It aligns a 2-byte value to an even offset and a value of 4 or more bytes to an 
  7240. offset divisible by 4. A record itself is aligned according to its field with 
  7241. largest alignment, e.g. if a record contains a field of the REAL type, its size 
  7242. will be multiple of 4 (SIZE(REAL) = 4). 
  7243.  
  7244.  
  7245. ΓòÉΓòÉΓòÉ 14.1.8. Array types ΓòÉΓòÉΓòÉ
  7246.  
  7247. An array is represented by a continuous memory segment containing all array 
  7248. elements in a representation corresponding to their type. 
  7249.  
  7250. Note that elements within an array could be aligned so, that in general for 
  7251.  
  7252.   TYPE A = ARRAY [0..N-1] OF T;
  7253.  
  7254. SIZE(A) is not equal to SIZE(T) * N. 
  7255.  
  7256. Open arrays, as well as procedure formal parameters of type ARRAY OF ... ARRAY 
  7257. OF T, are represented by an open array descriptor. For an N-dimensional open 
  7258. array, the descriptor is an array of 3N 32-bit elements, which are: 
  7259.  
  7260.      the first element the address of the array proper; 
  7261.  
  7262.      for each of N-1 higher dimensions, the descriptor contains three 
  7263.       consecutive signed integers, which are: 
  7264.  
  7265.         -  the lowest array index of this dimension (always 0); 
  7266.  
  7267.         -  the highest array index (the length of this dimension minus one); 
  7268.  
  7269.         -  the size of the array element in bytes; 
  7270.  
  7271.      for the last dimension, the array descriptor contains its lowest (0) and 
  7272.       highest indices. 
  7273.  
  7274.  Example: 
  7275.  
  7276.  let A be an open 3-dimensional array of INTEGER (SIZE(INTEGER)=2 in Oberon-2) 
  7277.  created as 
  7278.  
  7279.     NEW(A,4,3,6)
  7280.  
  7281.  then its descriptor is a 9-element array containing: 
  7282.  
  7283.        #0:  Address of array itself
  7284.        #1:   0
  7285.        #2:   3   (4-1)
  7286.        #3:  36   (12*3)
  7287.        #4:   0
  7288.        #5:   2   (3-1)
  7289.        #6:  12   (6*2)
  7290.        #7:   0
  7291.        #8:   5   (6-1)
  7292.  
  7293.  
  7294. ΓòÉΓòÉΓòÉ 14.2. Sequence parameters ΓòÉΓòÉΓòÉ
  7295.  
  7296. The array of bytes which is passed to a procedure in place of a formal 
  7297. SEQ-parameter is formed as follows: 
  7298.  
  7299.      values of all actual parameters forming the sequence are represented as 
  7300.       described below and concatenated in the array in their textual order 
  7301.  
  7302.      integer values are converted to LONGINT 
  7303.  
  7304.      BOOLEAN, CHAR, cardinal and enumeration values are converted to LONGCARD 
  7305.  
  7306.      range type values are converted according to their base type 
  7307.  
  7308.      real values are converted to LONGREAL 
  7309.  
  7310.      pointer, address, opaque and procedure type values are converted to 
  7311.       ADDRESS 
  7312.  
  7313.      structured value (record or array) is interpreted as one-dimensional 
  7314.       array of bytes and then is represented by an array descriptor (See ???). 
  7315.  
  7316.  Example 
  7317.  
  7318.       PROCEDURE write(SEQ args: SYSTEM.BYTE);
  7319.       BEGIN
  7320.       END write;
  7321.  
  7322.       VAR i: INTEGER;
  7323.           c: SYSTEM.CARD8;
  7324.           r: LONGREAL;
  7325.           S: RECORD a: LONGINT; c: CHAR END;
  7326.           p: POINTER TO ARRAY OF CHAR;
  7327.       ...
  7328.  
  7329.       write(i,c,S,r,p^);
  7330.  
  7331.  For this call the actual byte array passed to write will contain: 
  7332.  
  7333.      4 bytes of the sign-extended value of i 
  7334.  
  7335.      4 bytes of the zero-extended value of c 
  7336.  
  7337.      12 bytes of the array descriptor 
  7338.  
  7339.         -  4 bytes containing the address of S 
  7340.  
  7341.         -  4 bytes containing 0 
  7342.  
  7343.         -  4 bytes containing 4 (SIZE(S)-1) 
  7344.  
  7345.      8 bytes value of r in the double-precision 80387 format 
  7346.  
  7347.      12 bytes of the array descriptor 
  7348.  
  7349.         -  4 bytes containing the address of array of CHAR itself 
  7350.  
  7351.         -  4 bytes containing value 0 
  7352.  
  7353.         -  4 bytes containing SIZE(p^)-1 
  7354.  
  7355.  
  7356. ΓòÉΓòÉΓòÉ 15. Implementation limitations and restrictions ΓòÉΓòÉΓòÉ
  7357.  
  7358. There are some limitations and restrictions in both Modula-2 and Oberon-2 
  7359. compilers. 
  7360.  
  7361.  
  7362. ΓòÉΓòÉΓòÉ 15.1. Length of identifiers ΓòÉΓòÉΓòÉ
  7363.  
  7364. The length of an identifier is at most 127 characters. 
  7365.  
  7366.  
  7367. ΓòÉΓòÉΓòÉ 15.2. Length of literal strings ΓòÉΓòÉΓòÉ
  7368.  
  7369. The length of a literal string is at most 256 characters. Longer strings may be 
  7370. constructed by use of the string concatenation operator (See Strings). 
  7371.  
  7372.  
  7373. ΓòÉΓòÉΓòÉ 15.3. Record extension hierarchy ΓòÉΓòÉΓòÉ
  7374.  
  7375. The length of a record extension hierarchy is at most 15 extensions. 
  7376.  
  7377.  
  7378. ΓòÉΓòÉΓòÉ 15.4. Unimplemented ISO libraries ΓòÉΓòÉΓòÉ
  7379.  
  7380. The following Modula-2 ISO standard library modules are not available in the 
  7381. current release: 
  7382.  
  7383. The appearance of the following table is a known problem and will be improved 
  7384. in the final release. 
  7385.  
  7386. lp7cm TermFile | Access to an interactive terminal 
  7387.  LowLong | Access to underlying properties of the type LONGREAL 
  7388.  LowReal | Access to underlying properties of the type REAL 
  7389.  
  7390.  
  7391. ΓòÉΓòÉΓòÉ 15.5. Unimplemented Oakwood libraries ΓòÉΓòÉΓòÉ
  7392.  
  7393. The following Oberon-2 Oakwood library modules are not available in the current 
  7394. release: 
  7395.  
  7396. The appearance of the following table is a known problem and will be improved 
  7397. in the final release. 
  7398.  
  7399. lp7cm Input | Keyboard and pointer device access 
  7400.  Files | File input/output, riders 
  7401.  XYPlane | Elementary pixel plotting 
  7402.  
  7403.  
  7404. ΓòÉΓòÉΓòÉ 15.6. Coroutines ΓòÉΓòÉΓòÉ
  7405.  
  7406. The current release provides a restricted implementation of the system module 
  7407. COROUTINES: the interrupt requests are not detected. 
  7408.  
  7409.  
  7410. ΓòÉΓòÉΓòÉ 15.7. Dynamic loader ΓòÉΓòÉΓòÉ
  7411.  
  7412. The Oberon-2 dynamic loading facility is not provided in the current release, 
  7413.  
  7414. ReWi88 
  7415.  
  7416. [MoWi91]MW91 H.Mossenbock, N.Wirth. The Programming Language Oberon-2. 
  7417. Structured Programming,1991, 12, 179-195. 
  7418.  
  7419. [PIM]PIM N.Wirth. Programming in Modula-2. 4th edition. Springer-Verlag, 1988. 
  7420. ISBN 0-387-50150-9. 
  7421.  
  7422. [Wirth88]M2O2 N.Wirth. From Modula-2 to Oberon. Software, Practice and 
  7423. Experience 18:7(1988), 661-670. 
  7424.  
  7425. [ReWi92]PIO M.Reiser, N.Wirth. Programming in Oberon - Steps Beyond Pascal and 
  7426. Modula. ACM Press, Addison Wessley, 1992. ISBN 0-201-56543-9 
  7427.  
  7428. [Mo93]M93 H.Mossenbock. Object Oriented Programming in Oberon-2. 
  7429. Springer-Verlag, 1993. ISBN 3-540-56411-X 
  7430.  
  7431.  
  7432. ΓòÉΓòÉΓòÉ 16. The Oberon-2 Report ΓòÉΓòÉΓòÉ
  7433.  
  7434.  The Programming Language Oberon-2 
  7435.  H.Mossenbock, N. Wirth 
  7436.  Institut fur Computersysteme, 
  7437.  ETH Zurich 
  7438.  October 1993 
  7439.  
  7440.  
  7441. ΓòÉΓòÉΓòÉ 16.1. Introduction ΓòÉΓòÉΓòÉ
  7442.  
  7443. Oberon-2 is a general-purpose language in the tradition of Oberon and Modula-2. 
  7444. Its most important features are block structure, modularity, separate 
  7445. compilation, static typing with strong type checking (also across module 
  7446. boundaries), and type extension with type-bound procedures. 
  7447.  
  7448. Type extension makes Oberon-2 an object-oriented language. An object is a 
  7449. variable of an abstract data type consisting of private data (its state) and 
  7450. procedures that operate on this data. Abstract data types are declared as 
  7451. extensible records. Oberon-2 covers most terms of object-oriented languages by 
  7452. the established vocabulary of imperative languages in order to minimize the 
  7453. number of notions for similar concepts. 
  7454.  
  7455. This report is not intended as a programmer's tutorial. It is intentionally 
  7456. kept concise. Its function is to serve as a reference for programmers, 
  7457. implementors, and manual writers. What remains unsaid is mostly left so 
  7458. intentionally, either because it can be derived from stated rules of the 
  7459. language, or because it would require to commit the definition when a general 
  7460. commitment appears as unwise. 
  7461.  
  7462. Section Definition of terms defines some terms that are used to express the 
  7463. type checking rules of Oberon-2. Where they appear in the text, they are 
  7464. written in italics to indicate their special meaning (e.g. the same type). 
  7465.  
  7466.  
  7467. ΓòÉΓòÉΓòÉ 16.2. Syntax ΓòÉΓòÉΓòÉ
  7468.  
  7469. An extended Backus-Naur Formalism (EBNF) is used to describe the syntax of 
  7470. Oberon-2: Alternatives are separated by |. Brackets [ and ] denote optionality 
  7471. of the enclosed expression, and braces { and } denote its repetition (possibly 
  7472. 0 times). Non-terminal symbols start with an upper-case letter (e.g. 
  7473. Statement). Terminal symbols either start with a lower-case letter (e.g. 
  7474. ident), or are written all in upper-case letters (e.g. BEGIN), or are denoted 
  7475. by strings (e.g. ":="). 
  7476.  
  7477.  
  7478. ΓòÉΓòÉΓòÉ 16.3. Vocabulary and Representation ΓòÉΓòÉΓòÉ
  7479.  
  7480. The representation of (terminal) symbols in terms of characters is defined 
  7481. using the ASCII set. Symbols are identifiers, numbers, strings, operators, and 
  7482. delimiters. The following lexical rules must be observed: Blanks and line 
  7483. breaks must not occur within symbols (except in comments, and blanks in 
  7484. strings). They are ignored unless they are essential to separate two 
  7485. consecutive symbols. Capital and lower-case letters are considered as distinct. 
  7486. 1. 
  7487.  
  7488. Identifiers are sequences of letters and digits. The first character must be a 
  7489. letter. 
  7490.  
  7491.   ident = letter {letter | digit}.
  7492.  
  7493. Examples: 
  7494.  
  7495.   x   Scan   Oberon2   GetSymbol   firstLetter
  7496.  
  7497. 2. 
  7498.  
  7499. Numbers are (unsigned) integer or real constants. The type of an integer 
  7500. constant is the minimal type to which the constant value belongs (see Basic 
  7501. types). If the constant is specified with the suffix H, the representation is 
  7502. hexadecimal otherwise the representation is decimal. 
  7503.  
  7504. A real number always contains a decimal point. Optionally it may also contain a 
  7505. decimal scale factor. The letter E (or D) means "times ten to the power of". A 
  7506. real number is of type REAL, unless it has a scale factor containing the letter 
  7507. D. In this case it is of type LONGREAL. 
  7508.  
  7509.   number      = integer | real.
  7510.   integer     = digit {digit} | digit{hexDigit}"H".
  7511.   real        = digit{digit}"."{digit} [ScaleFactor].
  7512.   ScaleFactor = ("E" | "D") ["+" | "-"] digit {digit}.
  7513.   hexDigit    = digit |"A"|"B"|"C"|"D"|"E"|"F".
  7514.   digit       = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9".
  7515.  
  7516. Examples: 
  7517.  
  7518.   1991           INTEGER          1991
  7519.   0DH            SHORTINT         13
  7520.   12.3           REAL             12.3
  7521.   4.567E8        REAL             456700000
  7522.   0.57712566D-6  LONGREAL         0.00000057712566
  7523.  
  7524. 3. 
  7525.  
  7526. Character constants are denoted by the ordinal number of the character in 
  7527. hexadecimal notation followed by the letter X. 
  7528.  
  7529.   character = digit {hexDigit} "X".
  7530.  
  7531. 4. 
  7532.  
  7533. Strings are sequences of characters enclosed in single (') or double (") quote 
  7534. marks. The opening quote must be the same as the closing quote and must not 
  7535. occur within the string. The number of characters in a string is called its 
  7536. length. A string of length 1 can be used wherever a character constant is 
  7537. allowed and vice versa. 
  7538.  
  7539.   string = '"' {char} '"' | "'" {char} "'".
  7540.  
  7541. Examples: 
  7542.  
  7543.   "Oberon-2"     "Don't worry!"   "x"
  7544.  
  7545. 5. 
  7546.  
  7547. Operators and delimiters are the special characters, character pairs, or 
  7548. reserved words listed below. The reserved words consist exclusively of capital 
  7549. letters and cannot be used as identifiers. 
  7550.  
  7551.   +         :=         ARRAY    IMPORT     RETURN
  7552.   -         ^          BEGIN    IN         THEN
  7553.   *         =          BY       IS         TO
  7554.   /         #          CASE     LOOP       TYPE
  7555.   ~         <          CONST    MOD        UNTIL
  7556.   &         >          DIV      MODULE     VAR
  7557.   .         <=         DO       NIL        WHILE
  7558.   ,         >=         ELSE     OF         WITH
  7559.   ;         ..         ELSIF    OR
  7560.   |         :          END      POINTER
  7561.   (         )          EXIT     PROCEDURE
  7562.   [         ]          FOR      RECORD
  7563.   {         }          IF       REPEAT
  7564.  
  7565. 6. 
  7566.  
  7567. Comments may be inserted between any two symbols in a program. They are 
  7568. arbitrary character sequences opened by the bracket (* and closed by *). 
  7569. Comments may be nested. They do not affect the meaning of a program. 
  7570.  
  7571.  
  7572. ΓòÉΓòÉΓòÉ 16.4. Declarations and scope rules ΓòÉΓòÉΓòÉ
  7573.  
  7574. Every identifier occurring in a program must be introduced by a declaration, 
  7575. unless it is a predeclared identifier. Declarations also specify certain 
  7576. permanent properties of an object, such as whether it is a constant, a type, a 
  7577. variable, or a procedure. The identifier is then used to refer to the 
  7578. associated object. 
  7579.  
  7580. The scope of an object x extends textually from the point of its declaration to 
  7581. the end of the block (module, procedure, or record) to which the declaration 
  7582. belongs and hence to which the object is local. It excludes the scopes of 
  7583. equally named objects which are declared in nested blocks. The scope rules are: 
  7584.  
  7585.    1. No identifier may denote more than one object within a given scope (i.e. 
  7586.       no identifier may be declared twice in a block); 
  7587.  
  7588.    2. An object may only be referenced within its scope; 
  7589.  
  7590.    3. A type T of the form POINTER TO T1 (see Pointer types) can be declared 
  7591.       before the scope of T1. The declaration of T1 must follow in the same 
  7592.       block to which T is local; 
  7593.  
  7594.    4. Identifiers denoting record fields (see Record types) or type-bound 
  7595.       procedures (see Type-bound procedures) are valid in record designators 
  7596.       only. 
  7597.  
  7598.  An identifier declared in a module block may be followed by an export mark 
  7599.  ("*" or "-") in its declaration to indicate that it is exported. An identifier 
  7600.  x exported by a module M may be used in other modules, if they import M (see 
  7601.  section Modules). The identifier is then denoted as M.x in these modules and 
  7602.  is called a qualified identifier. Identifiers marked with "-" in their 
  7603.  declaration are read-only in importing modules. 
  7604.  
  7605.     Qualident = [ident "."]ident.
  7606.     IdentDef  = ident [" * " | " - "].
  7607.  
  7608.  The following identifiers are predeclared; their meaning is defined in the 
  7609.  indicated sections: 
  7610.  
  7611.  The appearance of the following table is a known problem and will be improved 
  7612.  in the final release. 
  7613.  
  7614.  ll@2.0cmll ABS | (Predeclared procedures) | LEN | (Predeclared procedures) 
  7615.   ASH | (Predeclared procedures) | LONG | (Predeclared procedures) 
  7616.   BOOLEAN | (Basic types) | LONGINT | (Basic types) 
  7617.   CAP | (Predeclared procedures) | LONGREAL | (Basic types) 
  7618.   CHAR | (Basic types) | MAX | (Predeclared procedures) 
  7619.   CHR | (Predeclared procedures) | MIN | (Predeclared procedures) 
  7620.   COPY | (Predeclared procedures) | NEW | (Predeclared procedures) 
  7621.   DEC | (Predeclared procedures) | ODD | (Predeclared procedures) 
  7622.   ENTIER | (Predeclared procedures) | ORD | (Predeclared procedures) 
  7623.   EXCL | (Predeclared procedures) | REAL | (Basic types) 
  7624.   FALSE | (Basic types) | SET | (Basic types) 
  7625.   HALT | (Predeclared procedures) | SHORT | (Predeclared procedures) 
  7626.   INC | (Predeclared procedures) | SHORTINT | (Basic types) 
  7627.   INCL | (Predeclared procedures) | SIZE | (Predeclared procedures) 
  7628.   INTEGER | (Basic types) | TRUE | (Basic types) 
  7629.  
  7630.  
  7631. ΓòÉΓòÉΓòÉ 16.5. Constant declarations ΓòÉΓòÉΓòÉ
  7632.  
  7633. A constant declaration associates an identifier with a constant value. 
  7634.  
  7635.   ConstantDeclaration = IdentDef "=" ConstExpression.
  7636.   ConstExpression     = Expression.
  7637.  
  7638. A constant expression is an expression that can be evaluated by a mere textual 
  7639. scan without actually executing the program. Its operands are constants 
  7640. (section Expressions) or predeclared functions (section Predeclared procedures) 
  7641. that can be evaluated at compile time. Examples of constant declarations are: 
  7642.  
  7643.   N = 100
  7644.   limit = 2*N - 1
  7645.   fullSet = {MIN(SET)..MAX(SET)}
  7646.  
  7647.  
  7648. ΓòÉΓòÉΓòÉ 16.6. Type declarations ΓòÉΓòÉΓòÉ
  7649.  
  7650. A data type determines the set of values which variables of that type may 
  7651. assume, and the operators that are applicable. A type declaration associates an 
  7652. identifier with a type. In the case of structured types (arrays and records) it 
  7653. also defines the structure of variables of this type. 
  7654.  
  7655.   TypeDeclaration = IdentDef "=" Type.
  7656.   Type            = Qualident | ArrayType | RecordType |
  7657.                     PointerType | ProcedureType.
  7658.  
  7659. Examples: 
  7660.  
  7661.   Table = ARRAY N OF REAL
  7662.   Tree =  POINTER TO Node
  7663.   Node =  RECORD
  7664.     key: INTEGER;
  7665.     left, right: Tree
  7666.   END
  7667.   CenterTree = POINTER TO CenterNode
  7668.   CenterNode = RECORD (Node)
  7669.     width: INTEGER;
  7670.     subnode: Tree
  7671.   END
  7672.   Function = PROCEDURE(x: INTEGER): INTEGER
  7673.  
  7674.  
  7675. ΓòÉΓòÉΓòÉ 16.6.1. Basic types ΓòÉΓòÉΓòÉ
  7676.  
  7677. The basic types are denoted by predeclared identifiers. The associated 
  7678. operators are defined in Operators and the predeclared function procedures in 
  7679. Predeclared procedures The values of the given basic types are the following: 
  7680.  
  7681. The appearance of the following table is a known problem and will be improved 
  7682. in the final release. 
  7683.  
  7684. llp7cm 1. |  BOOLEAN | the truth values TRUE and FALSE 
  7685.  2. |  CHAR | the characters of the extended ASCII set (0X..0FFX) 
  7686.  3. |  SHORTINT | the integers between MIN(SHORTINT) and MAX(SHORTINT) 
  7687.  4. |  INTEGER | the integers between MIN(INTEGER) and MAX(INTEGER) 
  7688.  5. |  LONGINT | the integers between MIN(LONGINT) and MAX(LONGINT) 
  7689.  6. |  REAL | the real numbers between MIN(REAL) and MAX(REAL) 
  7690.  7. |  LONGREAL | the real numbers between MIN(LONGREAL) and MAX(LONGREAL) 
  7691.  8. |  SET | the sets of integers between 0 and MAX(SET) 
  7692.  
  7693. Types 3 to 5 are integer types, types 6 and 7 are real types, and together they 
  7694. are called numeric types. They form a hierarchy; the larger type includes (the 
  7695. values of) the smaller type:  LONGREAL ?REAL ?LONGINT ?INTEGER ?SHORTINT 
  7696.  
  7697.  
  7698. ΓòÉΓòÉΓòÉ 16.6.2. Array types ΓòÉΓòÉΓòÉ
  7699.  
  7700. An array is a structure consisting of a number of elements which are all of the 
  7701. same type, called the element type. The number of elements of an array is 
  7702. called its length. The elements of the array are designated by indices, which 
  7703. are integers between 0 and the length minus 1. 
  7704.  
  7705.   ArrayType = ARRAY [ Length { "," Length}] OF Type.
  7706.   Length    = ConstExpression.
  7707.  
  7708. A type of the form 
  7709.  
  7710.    ARRAY L0, L1, ..., Ln OF T
  7711.  
  7712. is understood as an abbreviation of 
  7713.  
  7714.    ARRAY L0 OF
  7715.      ARRAY L1 OF
  7716.      ...
  7717.        ARRAY Ln OF T
  7718.  
  7719. Arrays declared without length are called open arrays. They are restricted to 
  7720. pointer base types (see Pointer types), element types of open array types, and 
  7721. formal parameter types (see Formal parameters). Examples: 
  7722.  
  7723.    ARRAY 10, N OF INTEGER
  7724.    ARRAY OF CHAR
  7725.  
  7726.  
  7727. ΓòÉΓòÉΓòÉ 16.6.3. Record types ΓòÉΓòÉΓòÉ
  7728.  
  7729. A record type is a structure consisting of a fixed number of elements, called 
  7730. fields, with possibly different types. The record type declaration specifies 
  7731. the name and type of each field. The scope of the field identifiers extends 
  7732. from the point of their declaration to the end of the record type, but they are 
  7733. also visible within designators referring to elements of record variables (see 
  7734. Operands). If a record type is exported, field identifiers that are to be 
  7735. visible outside the declaring module must be marked. They are called public 
  7736. fields; unmarked elements are called private fields. 
  7737.  
  7738. RecordType = RECORD ["("BaseType")"]
  7739.                FieldList{";" FieldList}
  7740.              END.
  7741. BaseType   = Qualident.
  7742. FieldList  = [IdentList ":" Type ].
  7743.  
  7744. Record types are extensible, i.e. a record type can be declared as an extension 
  7745. of another record type. In the example 
  7746.  
  7747.    T0 = RECORD x: INTEGER END
  7748.    T1 = RECORD (T0) y: REAL END
  7749.  
  7750. T1 is a (direct) extension of T0 and T0 is the (direct) base type of T1 (see 
  7751. section Definition of terms). An extended type T1 consists of the fields of its 
  7752. base type and of the fields which are declared in T1 (see section Type 
  7753. declarations). All identifiers declared in the extended record must be 
  7754. different from the identifiers declared in its base type record(s). 
  7755.  
  7756. Examples of record type declarations: 
  7757.  
  7758.   RECORD
  7759.     day, month, year: INTEGER
  7760.   END
  7761.  
  7762.   RECORD
  7763.     name, firstname: ARRAY 32 OF CHAR;
  7764.     age: INTEGER;
  7765.     salary: REAL
  7766.   END
  7767.  
  7768.  
  7769. ΓòÉΓòÉΓòÉ 16.6.4. Pointer types ΓòÉΓòÉΓòÉ
  7770.  
  7771. Variables of a pointer type P assume as values pointers to variables of some 
  7772. type T. T is called the pointer base type of P and must be a record or array 
  7773. type. Pointer types adopt the extension relation of their pointer base types: 
  7774. if a type T1 is an extension of T, and P1 is of type POINTER TO T1, then P1 is 
  7775. also an extension of P. 
  7776.  
  7777.   PointerType = POINTER TO Type.
  7778.  
  7779. If p is a variable of type P = POINTER TO T, a call of the predeclared 
  7780. procedure NEW(p) (see Predeclared procedures) allocates a variable of type T in 
  7781. free storage. If T is a record type or an array type with fixed length, the 
  7782. allocation has to be done with NEW(p); if T is an n-dimensional open array type 
  7783. the allocation has to be done with NEW(p,e0,,en-1) where T is allocated with 
  7784. lengths given by the expressions e0,,en-1. In either case a pointer to the 
  7785. allocated variable is assigned to p. p is of type P. The referenced variable 
  7786. p'136(pronounced as p-referenced) is of type T. Any pointer variable may assume 
  7787. the value NIL, which points to no variable at all. 
  7788.  
  7789.  
  7790. ΓòÉΓòÉΓòÉ 16.6.5. Procedure types ΓòÉΓòÉΓòÉ
  7791.  
  7792. Variables of a procedure type T have a procedure (or NIL) as value. If a 
  7793. procedure P is assigned to a variable of type T, the formal parameter lists 
  7794. (see section Formal parameters) of P and T must match (see Definition of 
  7795. terms). P must not be a predeclared or type-bound procedure nor may it be local 
  7796. to another procedure. 
  7797.  
  7798.   ProcedureType  = PROCEDURE [FormalParameters].
  7799.  
  7800.  
  7801. ΓòÉΓòÉΓòÉ 16.7. Variable declarations ΓòÉΓòÉΓòÉ
  7802.  
  7803. Variable declarations introduce variables by defining an identifier and a data 
  7804. type for them. 
  7805.  
  7806.   VariableDeclaration = IdentList ":" Type.
  7807.  
  7808. Record and pointer variables have both a static type (the type with which they 
  7809. are declared - simply called their type) and a dynamic type (the type they 
  7810. assume at run time). For pointers and variable parameters of record type the 
  7811. dynamic type may be an extension of their static type. The static type 
  7812. determines which fields of a record are accessible. The dynamic type is used to 
  7813. call type-bound procedures (see Type-bound procedures). 
  7814.  
  7815. Examples of variable declarations (refer to examples in Type declarations): 
  7816.  
  7817.   i, j, k: INTEGER
  7818.   x, y: REAL
  7819.   p, q: BOOLEAN
  7820.   s: SET
  7821.   F: Function
  7822.   a: ARRAY 100 OF REAL
  7823.   w: ARRAY 16 OF RECORD
  7824.        name  : ARRAY 32 OF CHAR;
  7825.        ccount: INTEGER
  7826.      END
  7827.   t, c: Tree
  7828.  
  7829.  
  7830. ΓòÉΓòÉΓòÉ 16.8. Expressions ΓòÉΓòÉΓòÉ
  7831.  
  7832. Expressions are constructs denoting rules of computation whereby constants and 
  7833. current values of variables are combined to compute other values by the 
  7834. application of operators and function procedures. Expressions consist of 
  7835. operands and operators. Parentheses may be used to express specific 
  7836. associations of operators and operands. 
  7837.  
  7838.  
  7839. ΓòÉΓòÉΓòÉ 16.8.1. Operands ΓòÉΓòÉΓòÉ
  7840.  
  7841. With the exception of set constructors and literal constants (numbers, 
  7842. character constants, or strings), operands are denoted by designators. A 
  7843. designator consists of an identifier referring to a constant, variable, or 
  7844. procedure. This identifier may possibly be qualified by a module identifier 
  7845. (see sections Declarations and scope rules and Modules) and may be followed by 
  7846. selectors if the designated object is an element of a structure. 
  7847.  
  7848.   Designator     = Qualident { "." ident |
  7849.                    "[" ExpressionList "]" |
  7850.                    "^" | "(" Qualident ")" }.
  7851.   ExpressionList = Expression {"," Expression}.
  7852.  
  7853. If a designates an array, then a[e] denotes that element of a whose index is 
  7854. the current value of the expression e. The type of e must be an integer type. A 
  7855. designator of the form a[e0,e1,,en] stands for a[e0][e1][en]. If r designates a 
  7856. record, then r.f denotes the field f of r or the procedure f bound to the 
  7857. dynamic type of r (section Type-bound procedures). If p designates a pointer, 
  7858. p'136 denotes the variable which is referenced by p. The designators p'136.f 
  7859. and p'136[e] may be abbreviated as p.f and p[e], i.e. record and array 
  7860. selectors imply dereferencing. If a or r are read-only, then also a[e] and r.f 
  7861. are read-only. 
  7862.  
  7863. A type guard  v(T) asserts that the dynamic type of v is T (or an extension of 
  7864. T), i.e. program execution is aborted, if the dynamic type of v is not T (or an 
  7865. extension of T). Within the designator, v is then regarded as having the static 
  7866. type T. The guard is applicable, if 
  7867.  
  7868.    1. v is a variable parameter of record type or v is a pointer, and if 
  7869.  
  7870.    2. T is an extension of the static type of v 
  7871.  
  7872.  If the designated object is a constant or a variable, then the designator 
  7873.  refers to its current value. If it is a procedure, the designator refers to 
  7874.  that procedure unless it is followed by a (possibly empty) parameter list in 
  7875.  which case it implies an activation of that procedure and stands for the value 
  7876.  resulting from its execution. The actual parameters must correspond to the 
  7877.  formal parameters as in proper procedure calls (see Formal parameters). 
  7878.  
  7879.  Examples of designators (refer to examples in Variable declarations): 
  7880.  
  7881.     i                       (INTEGER)
  7882.     a[i]                    (REAL)
  7883.     w[3].name[i]            (CHAR)
  7884.     t.left.right            (Tree)
  7885.     t(CenterNode).subnode   (Tree)
  7886.  
  7887.  
  7888. ΓòÉΓòÉΓòÉ 16.8.2. Operators ΓòÉΓòÉΓòÉ
  7889.  
  7890. Four classes of operators with different precedences (binding strengths) are 
  7891. syntactically distinguished in expressions. The operator ~ has the highest 
  7892. precedence, followed by multiplication operators, addition operators, and 
  7893. relations. Operators of the same precedence associate from left to right. For 
  7894. example, x-y-z stands for (x-y)-z. 
  7895.  
  7896.   Expression       = SimpleExpression
  7897.                      [ Relation SimpleExpression].
  7898.   SimpleExpression = ["+" | "-"] Term {AddOperator Term}.
  7899.   Term             = Factor {MulOperator Factor}.
  7900.   Factor           = Designator [ActualParameters] |
  7901.                      number | character | string | NIL |
  7902.                      Set | "(" Expression ")" | "~" Factor.
  7903.   Set              = "{"[Element {","Element}]"}".
  7904.   Element          = Expression [".."Expression].
  7905.   ActualParameters = "(" [ExpressionList] ")".
  7906.   Relation         = "=" | "#" | "<" | "<=" | ">" | ">=" |
  7907.                      IN | IS.
  7908.   AddOperator      = "+" | "-" | OR.
  7909.   MulOperator      = "*" | "/" | DIV | MOD | "&".
  7910.  
  7911. The available operators are listed in the following tables. Some operators are 
  7912. applicable to operands of various types, denoting different operations. In 
  7913. these cases, the actual operation is identified by the type of the operands. 
  7914. The operands must be expression compatible with respect to the operator (see 
  7915. Definition of terms). 
  7916. Logical operators 
  7917.  
  7918. The appearance of the following table is a known problem and will be improved 
  7919. in the final release. 
  7920.  
  7921. llll OR | logical disjunction | p OR q | "if p then TRUE, else q" 
  7922.  & | logical conjunction | p & q | "if p then q, else FALSE" 
  7923.  ~ | negation | ~p | "not p" 
  7924.  
  7925. These operators apply to BOOLEAN operands and yield a BOOLEAN result. 
  7926. Arithmetic operators 
  7927.  
  7928. The appearance of the following table is a known problem and will be improved 
  7929. in the final release. 
  7930.  
  7931. ll + | sum 
  7932.  - | difference 
  7933.  * | product 
  7934.  / | real quotient 
  7935.  DIV | integer quotient 
  7936.  MOD | modulus 
  7937.  
  7938. The operators +, -, *, and / apply to operands of numeric types. The type of 
  7939. the result is the type of that operand which includes the type of the other 
  7940. operand, except for division (/), where the result is the smallest real type 
  7941. which includes both operand types. When used as monadic operators, - denotes 
  7942. sign inversion and + denotes the identity operation. The operators DIV and MOD 
  7943. apply to integer operands only. They are related by the following formulas 
  7944. defined for any x and positive divisors y: 
  7945.  
  7946.   x = (x DIV y) * y + (x MOD y)
  7947.   0 <= (x MOD y) < y
  7948.  
  7949. Examples: 
  7950.  
  7951. The appearance of the following table is a known problem and will be improved 
  7952. in the final release. 
  7953.  
  7954. cccc x | y | x DIV y | x MOD y 
  7955.  5 | 3 | 1 | 2 
  7956.  -5 | 3 | -2 | 1 
  7957.  
  7958. Set Operators 
  7959.  
  7960. The appearance of the following table is a known problem and will be improved 
  7961. in the final release. 
  7962.  
  7963. ll + | union 
  7964.  - | difference (x - y = x * (-y)) 
  7965.  * | intersection 
  7966.  / | symmetric set difference (x / y = (x-y) + (y-x)) 
  7967.  
  7968. Set operators apply to operands of type SET and yield a result of type SET. The 
  7969. monadic minus sign denotes the complement of x, i.e. -x denotes the set of 
  7970. integers between 0 and MAX(SET) which are not elements of x. Set operators are 
  7971. not associative ((a+b)-c # a+(b-c)). 
  7972.  
  7973. A set constructor defines the value of a set by listing its elements between 
  7974. curly brackets. The elements must be integers in the range 0..MAX(SET). A range 
  7975. a..b denotes all integers in the interval [a, b]. 
  7976. Relations 
  7977.  
  7978. The appearance of the following table is a known problem and will be improved 
  7979. in the final release. 
  7980.  
  7981. ll = | equal 
  7982.  # | unequal 
  7983.  < | less 
  7984.  <=| less or equal 
  7985.  > | greater 
  7986.  >=| greater or equal 
  7987.  IN| set membership 
  7988.  IS| type test 
  7989.  
  7990. Relations yield a BOOLEAN result. The relations =, #, <, <=, > and >= apply to 
  7991. the numeric types, CHAR, strings, and character arrays containing 0X as a 
  7992. terminator. The relations = and # also apply to BOOLEAN and SET, as well as to 
  7993. pointer and procedure types (including the value NIL). x IN s stands for "x is 
  7994. an element of s". x must be of an integer type, and s of type SET. v IS T 
  7995. stands for "the dynamic type of v is T (or an extension of T)" and is called a 
  7996. type test. It is applicable if 
  7997.  
  7998.    1. v is a variable parameter of record type or v is a pointer, and if 
  7999.  
  8000.    2. T is an extension of the static type of v 
  8001.  
  8002.  Examples of expressions (refer to examples in Variable declarations): 
  8003.  
  8004.     1991                    INTEGER
  8005.     i DIV 3                 INTEGER
  8006.     ~p OR q                 BOOLEAN
  8007.     (i+j) * (i-j)           INTEGER
  8008.     s - {8, 9, 13}          SET
  8009.     i + x                   REAL
  8010.     a[i+j] * a[i-j]         REAL
  8011.     (0<=i) & (i<100)        BOOLEAN
  8012.     t.key = 0               BOOLEAN
  8013.     k IN {i..j-1}           BOOLEAN
  8014.     w[i].name <= "John"     BOOLEAN
  8015.     t IS CenterNode         BOOLEAN
  8016.  
  8017.  
  8018. ΓòÉΓòÉΓòÉ 16.9. Statements ΓòÉΓòÉΓòÉ
  8019.  
  8020. Statements denote actions. There are elementary and structured statements. 
  8021. Elementary statements are not composed of any parts that are themselves 
  8022. statements. They are the assignment, the procedure call, the return, and the 
  8023. exit statement. Structured statements are composed of parts that are themselves 
  8024. statements. They are used to express sequencing and conditional, selective, and 
  8025. repetitive execution. A statement may also be empty, in which case it denotes 
  8026. no action. The empty statement is included in order to relax punctuation rules 
  8027. in statement sequences. 
  8028.  
  8029.   Statement =
  8030.     [ Assignment | ProcedureCall | IfStatement |
  8031.       CaseStatement | WhileStatement | RepeatStatement |
  8032.       ForStatement | LoopStatement | WithStatement |
  8033.       EXIT | RETURN [Expression]
  8034.     ].
  8035.  
  8036.  
  8037. ΓòÉΓòÉΓòÉ 16.9.1. Assignments ΓòÉΓòÉΓòÉ
  8038.  
  8039. Assignments replace the current value of a variable by a new value specified by 
  8040. an expression. The expression must be assignment compatible with the variable 
  8041. (see Definition of terms). The assignment operator is written as ":=" and 
  8042. pronounced as becomes. 
  8043.  
  8044.   Assignment = Designator ":=" Expression.
  8045.  
  8046. If an expression e of type Te is assigned to a variable v of type Tv, the 
  8047. following happens: 
  8048.  
  8049.    1. if Tv and Te are record types, only those fields of Te are assigned which 
  8050.       also belong to Tv (projection); the dynamic type of v must be the same as 
  8051.       the static type of v and is not changed by the assignment; 
  8052.  
  8053.    2. if Tv and Te are pointer types, the dynamic type of v becomes the dynamic 
  8054.       type of e; 
  8055.  
  8056.    3. if Tv is ARRAY n OF CHAR and e is a string of length m < n, v[i] becomes 
  8057.       ei for i=0..m-1 and v[m] becomes 0X. 
  8058.  
  8059.  Examples of assignments (refer to examples in Variable declarations): 
  8060.  
  8061.  The appearance of the following table is a known problem and will be improved 
  8062.  in the final release. 
  8063.  
  8064.  ll i := 0 
  8065.   p := i = j 
  8066.   x := i + 1 
  8067.   k := log2(i+j) 
  8068.   F := log2 | (* see Formal parameters *) 
  8069.   s := {2, 3, 5, 7, 11, 13} 
  8070.   a[i] := (x+y) * (x-y) 
  8071.   t.key := i 
  8072.   w[i+1].name := "John" 
  8073.   t := c 
  8074.  
  8075.  
  8076. ΓòÉΓòÉΓòÉ 16.9.2. Procedure calls ΓòÉΓòÉΓòÉ
  8077.  
  8078. A procedure call activates a procedure. It may contain a list of actual 
  8079. parameters which replace the corresponding formal parameters defined in the 
  8080. procedure declaration (see section Procedure types). The correspondence is 
  8081. established by the positions of the parameters in the actual and formal 
  8082. parameter lists. There are two kinds of parameters: variable and value 
  8083. parameters. 
  8084.  
  8085. If a formal parameter is a variable parameter, the corresponding actual 
  8086. parameter must be a designator denoting a variable. If it denotes an element of 
  8087. a structured variable, the component selectors are evaluated when the 
  8088. formal/actual parameter substitution takes place, i.e. before the execution of 
  8089. the procedure. If a formal parameter is a value parameter, the corresponding 
  8090. actual parameter must be an expression. This expression is evaluated before the 
  8091. procedure activation, and the resulting value is assigned to the formal 
  8092. parameter (see also Formal parameters). 
  8093.  
  8094.   ProcedureCall = Designator [ActualParameters].
  8095.  
  8096. Examples: 
  8097.  
  8098. The appearance of the following table is a known problem and will be improved 
  8099. in the final release. 
  8100.  
  8101. ll WriteInt(i*2+1) | (* see Formal parameters *) 
  8102.  INC(w[k].count) 
  8103.  t.Insert("John") | (* see Modules *) 
  8104.  
  8105.  
  8106. ΓòÉΓòÉΓòÉ 16.9.3. Statement sequences ΓòÉΓòÉΓòÉ
  8107.  
  8108. Statement sequences denote the sequence of actions specified by the component 
  8109. statements which are separated by semicolons. 
  8110.  
  8111.   StatementSequence = Statement {";" Statement}.
  8112.  
  8113.  
  8114. ΓòÉΓòÉΓòÉ 16.9.4. If statements ΓòÉΓòÉΓòÉ
  8115.  
  8116.   IfStatement =
  8117.          IF Expression THEN StatementSequence
  8118.        { ELSIF Expression THEN StatementSequence }
  8119.        [ ELSE StatementSequence ]
  8120.          END.
  8121.  
  8122. If statements specify the conditional execution of guarded statement sequences. 
  8123. The Boolean expression preceding a statement sequence is called its guard. The 
  8124. guards are evaluated in sequence of occurrence, until one evaluates to TRUE, 
  8125. whereafter its associated statement sequence is executed. If no guard is 
  8126. satisfied, the statement sequence following the symbol ELSE is executed, if 
  8127. there is one. 
  8128.  
  8129. Example: 
  8130.  
  8131.   IF (ch >= "A") & (ch <= "Z") THEN ReadIdentifier
  8132.   ELSIF (ch >= "0") & (ch <= "9") THEN ReadNumber
  8133.   ELSIF (ch = " ' ") OR (ch = '"') THEN ReadString
  8134.   ELSE SpecialCharacter
  8135.   END;
  8136.  
  8137.  
  8138. ΓòÉΓòÉΓòÉ 16.9.5. Case statements ΓòÉΓòÉΓòÉ
  8139.  
  8140. Case statements specify the selection and execution of a statement sequence 
  8141. according to the value of an expression. First the case expression is 
  8142. evaluated, then that statement sequence is executed whose case label list 
  8143. contains the obtained value. The case expression must either be of an integer 
  8144. type that includes the types of all case labels, or both the case expression 
  8145. and the case labels must be of type CHAR. Case labels are constants, and no 
  8146. value must occur more than once. If the value of the expression does not occur 
  8147. as a label of any case, the statement sequence following the symbol ELSE is 
  8148. selected, if there is one, otherwise the program is aborted. 
  8149.  
  8150.   CaseStatement = CASE Expression OF Case {"|" Case}
  8151.                   [ ELSE StatementSequence ]
  8152.                   END.
  8153.   Case          = [CaseLabelList ":" StatementSequence].
  8154.   CaseLabelList = CaseLabels {"," CaseLabels}.
  8155.   CaseLabels    = ConstExpression [ ".." ConstExpression].
  8156.  
  8157. Example: 
  8158.  
  8159.   CASE ch OF
  8160.     "A" .. "Z": ReadIdentifier
  8161.   | "0" .. "9": ReadNumber
  8162.   | "'", '"'  : ReadString
  8163.   ELSE SpecialCharacter
  8164.   END
  8165.  
  8166.  
  8167. ΓòÉΓòÉΓòÉ 16.9.6. While statements ΓòÉΓòÉΓòÉ
  8168.  
  8169. While statements specify the repeated execution of a statement sequence while 
  8170. the Boolean expression (its guard) yields TRUE. The guard is checked before 
  8171. every execution of the statement sequence. 
  8172.  
  8173.   WhileStatement = WHILE Expression DO StatementSequence END.
  8174.  
  8175. Examples: 
  8176.  
  8177.   WHILE i > 0 DO i := i DIV 2; k := k + 1 END
  8178.   WHILE (t # NIL) & (t.key # i) DO t := t.left END
  8179.  
  8180.  
  8181. ΓòÉΓòÉΓòÉ 16.9.7. Repeat statements ΓòÉΓòÉΓòÉ
  8182.  
  8183. A repeat statement specifies the repeated execution of a statement sequence 
  8184. until a condition specified by a Boolean expression is satisfied. The statement 
  8185. sequence is executed at least once. 
  8186.  
  8187.   RepeatStatement = REPEAT StatementSequence UNTIL Expression.
  8188.  
  8189.  
  8190. ΓòÉΓòÉΓòÉ 16.9.8. For statements ΓòÉΓòÉΓòÉ
  8191.  
  8192. A for statement specifies the repeated execution of a statement sequence for a 
  8193. fixed number of times while a progression of values is assigned to an integer 
  8194. variable called the control variable of the for statement. 
  8195.  
  8196.   ForStatement = FOR ident":="Expression TO Expression
  8197.                  [ BY ConstExpression ] DO StatementSequence
  8198.                  END.
  8199.  
  8200. The statement 
  8201.  
  8202.   FOR v := beg TO end BY step DO statements END
  8203.  
  8204. is equivalent to 
  8205.  
  8206.   temp := end; v := beg;
  8207.   IF step > 0 THEN
  8208.     WHILE v <= temp DO statements; v := v + step END
  8209.   ELSE
  8210.     WHILE v >= temp DO statements; v := v + step END
  8211.   END;
  8212.  
  8213. temp has the same type as v. step must be a non-zero constant expression. If 
  8214. step is not specified, it is assumed to be 1. 
  8215.  
  8216. Examples: 
  8217.  
  8218.   FOR i := 0 TO 79 DO k := k + a[i] END
  8219.   FOR i := 79 TO 1 BY -1 DO a[i] := a[i-1] END
  8220.  
  8221.  
  8222. ΓòÉΓòÉΓòÉ 16.9.9. Loop statements ΓòÉΓòÉΓòÉ
  8223.  
  8224. A loop statement specifies the repeated execution of a statement sequence. It 
  8225. is terminated upon execution of an exit statement within that sequence (see 
  8226. Return and exit statements). 
  8227.  
  8228.   LoopStatement = LOOP StatementSequence END.
  8229.  
  8230. Example: 
  8231.  
  8232.   LOOP
  8233.     ReadInt(i);
  8234.     IF i < 0 THEN EXIT END;
  8235.     WriteInt(i)
  8236.   END
  8237.  
  8238. Loop statements are useful to express repetitions with several exit points or 
  8239. cases where the exit condition is in the middle of the repeated statement 
  8240. sequence. 
  8241.  
  8242.  
  8243. ΓòÉΓòÉΓòÉ 16.9.10. Return and exit statements ΓòÉΓòÉΓòÉ
  8244.  
  8245. A return statement indicates the termination of a procedure. It is denoted by 
  8246. the symbol RETURN, followed by an expression if the procedure is a function 
  8247. procedure. The type of the expression must be assignment compatible (see 
  8248. Definition of terms) with the result type specified in the procedure heading 
  8249. (see section Procedure declarations). 
  8250.  
  8251. Function procedures require the presence of a return statement indicating the 
  8252. result value. In proper procedures, a return statement is implied by the end of 
  8253. the procedure body. Any explicit return statement therefore appears as an 
  8254. additional (probably exceptional) termination point. 
  8255.  
  8256. An exit statement is denoted by the symbol EXIT. It specifies termination of 
  8257. the enclosing loop statement and continuation with the statement following that 
  8258. loop statement. Exit statements are contextually, although not syntactically 
  8259. associated with the loop statement which contains them. 
  8260.  
  8261.  
  8262. ΓòÉΓòÉΓòÉ 16.9.11. With statements ΓòÉΓòÉΓòÉ
  8263.  
  8264. With statements execute a statement sequence depending on the result of a type 
  8265. test and apply a type guard to every occurrence of the tested variable within 
  8266. this statement sequence. 
  8267.  
  8268.   WithStatement = WITH Guard DO StatementSequence
  8269.                   { "|" Guard DO StatementSequence }
  8270.                   [ ELSE StatementSequence ]
  8271.                   END.
  8272.   Guard         = Qualident ":" Qualident.
  8273.  
  8274. If v is a variable parameter of record type or a pointer variable, and if it is 
  8275. of a static type T0, the statement 
  8276.  
  8277.   WITH v: T1 DO S1 |v: T2 DO S2 ELSE S3 END
  8278.  
  8279. has the following meaning: if the dynamic type of v is T1, then the statement 
  8280. sequence S1 is executed where v is regarded as if it had the static type T1; 
  8281. else if the dynamic type of v is T2, then S2 is executed where v is regarded as 
  8282. if it had the static type T2; else S3 is executed. T1 and T2 must be extensions 
  8283. of T0. If no type test is satisfied and if an else clause is missing the 
  8284. program is aborted. 
  8285.  
  8286. Example: 
  8287.  
  8288.   WITH t: CenterTree DO i := t.width; c := t.subnode END
  8289.  
  8290.  
  8291. ΓòÉΓòÉΓòÉ 16.10. Procedure declarations ΓòÉΓòÉΓòÉ
  8292.  
  8293. A procedure declaration consists of a procedure heading and a procedure body. 
  8294. The heading specifies the procedure identifier and the formal parameters. For 
  8295. type-bound procedures it also specifies the receiver parameter. The body 
  8296. contains declarations and statements. The procedure identifier is repeated at 
  8297. the end of the procedure declaration. 
  8298.  
  8299. There are two kinds of procedures: proper procedures and function procedures. 
  8300. The latter are activated by a function designator as a constituent of an 
  8301. expression and yield a result that is an operand of the expression. Proper 
  8302. procedures are activated by a procedure call. A procedure is a function 
  8303. procedure if its formal parameters specify a result type. The body of a 
  8304. function procedure must contain a return statement which defines its result. 
  8305.  
  8306. All constants, variables, types, and procedures declared within a procedure 
  8307. body are local to the procedure. Since procedures may be declared as local 
  8308. objects too, procedure declarations may be nested. The call of a procedure 
  8309. within its declaration implies recursive activation. 
  8310.  
  8311. Objects declared in the environment of the procedure are also visible in those 
  8312. parts of the procedure in which they are not concealed by a locally declared 
  8313. object with the same name. 
  8314.  
  8315.   ProcedureDeclaration =
  8316.       ProcedureHeading ";" ProcedureBody ident
  8317.   ProcedureHeading     =
  8318.       PROCEDURE [Receiver] IdentDef [FormalParameters].
  8319.   ProcedureBody        =
  8320.       DeclarationSequence [ BEGIN StatementSequence ] END.
  8321.   DeclarationSequence  =
  8322.       { CONST { ConstantDeclaration";" } |
  8323.         TYPE { TypeDeclaration ";" } |
  8324.         VAR { VariableDeclaration ";" }
  8325.       } |
  8326.       { ProcedureDeclaration ";" | ForwardDeclaration ";" }.
  8327.   ForwardDeclaration   =
  8328.       PROCEDURE "^"[Receiver] IdentDef [FormalParameters].
  8329.  
  8330. If a procedure declaration specifies a receiver parameter, the procedure is 
  8331. considered to be bound to a type (see Type-bound procedures). A forward 
  8332. declaration serves to allow forward references to a procedure whose actual 
  8333. declaration appears later in the text. The formal parameter lists of the 
  8334. forward declaration and the actual declaration must match (see Definition of 
  8335. terms). 
  8336.  
  8337.  
  8338. ΓòÉΓòÉΓòÉ 16.10.1. Formal parameters ΓòÉΓòÉΓòÉ
  8339.  
  8340. Formal parameters are identifiers declared in the formal parameter list of a 
  8341. procedure. They correspond to actual parameters specified in the procedure 
  8342. call. The correspondence between formal and actual parameters is established 
  8343. when the procedure is called. There are two kinds of parameters, value and 
  8344. variable parameters, indicated in the formal parameter list by the absence or 
  8345. presence of the keyword VAR. Value parameters are local variables to which the 
  8346. value of the corresponding actual parameter is assigned as an initial value. 
  8347. Variable parameters correspond to actual parameters that are variables, and 
  8348. they stand for these variables. The scope of a formal parameter extends from 
  8349. its declaration to the end of the procedure block in which it is declared. A 
  8350. function procedure without parameters must have an empty parameter list. It 
  8351. must be called by a function designator whose actual parameter list is empty 
  8352. too. The result type of a procedure can be neither a record nor an array. 
  8353.  
  8354.   FormalParameters = "(" [FPSection {";"FPSection}] ")"
  8355.                      [ ":" Qualident ].
  8356.   FPSection        = [VAR] ident {"," ident} ":" Type.
  8357.  
  8358. Let Tf be the type of a formal parameter f (not an open array) and Ta the type 
  8359. of the corresponding actual parameter a. For variable parameters, Ta must be 
  8360. the same as Tf, or Tf must be a record type and Ta an extension of Tf. For 
  8361. value parameters, a must be assignment compatible with f (see Definition of 
  8362. terms). If Tf is an open array, then a must be array compatible with f (see 
  8363. Definition of terms). The lengths of f are taken from a. 
  8364.  
  8365. Examples of procedure declarations: 
  8366.  
  8367.   PROCEDURE ReadInt(VAR x: INTEGER);
  8368.     VAR i: INTEGER; ch: CHAR;
  8369.   BEGIN
  8370.     i := 0;
  8371.     Read(ch);
  8372.     WHILE ("0" <= ch) & (ch >= "9") DO
  8373.       i:= 10*i + (ORD(ch)-ORD("0"));
  8374.       Read(ch)
  8375.     END;
  8376.     x := i;
  8377.   END ReadInt
  8378.  
  8379.   PROCEDURE WriteInt(x: INTEGER);
  8380.     (* 0 <= x <= 100000 *)
  8381.     VAR i: INTEGER; buf: ARRAY 5 OF INTEGER;
  8382.   BEGIN
  8383.     i := 0;
  8384.     REPEAT
  8385.       buf[i] := x MOD 10;
  8386.       x := x DIV 10;
  8387.       INC(i)
  8388.     UNTIL x = 0;
  8389.     REPEAT
  8390.       DEC(i);
  8391.       Write(CHR(buf[i] + ORD("0")))
  8392.     UNTIL i = 0;
  8393.   END WriteInt
  8394.  
  8395.   PROCEDURE WriteString(s: ARRAY OF CHAR);
  8396.     VAR i: INTEGER;
  8397.   BEGIN
  8398.     i := 0;
  8399.     WHILE (i < LEN(s)) & (s[i] # 0X) DO
  8400.       Write(s[i]);
  8401.       INC(i)
  8402.     END
  8403.   END WriteString
  8404.  
  8405.   PROCEDURE log2(x: INTEGER): INTEGER;
  8406.     VAR y: INTEGER; (* assume x>0 *)
  8407.   BEGIN
  8408.     y := 0;
  8409.     WHILE x > 1 DO x := x DIV 2; INC(y) END;
  8410.     RETURN y
  8411.   END log2
  8412.  
  8413.  
  8414. ΓòÉΓòÉΓòÉ 16.10.2. Type-bound procedures ΓòÉΓòÉΓòÉ
  8415.  
  8416. Globally declared procedures may be associated with a record type declared in 
  8417. the same module. The procedures are said to be bound to the record type. The 
  8418. binding is expressed by the type of the receiver in the heading of a procedure 
  8419. declaration. The receiver may be either a variable parameter of record type T 
  8420. or a value parameter of type POINTER TO T (where T is a record type). The 
  8421. procedure is bound to the type T and is considered local to it. 
  8422.  
  8423.   ProcedureHeading =
  8424.         PROCEDURE [Receiver] IdentDef [FormalParameters].
  8425.   Receiver         = "(" [VAR] ident ":" ident ")".
  8426.  
  8427. If a procedure P is bound to a type T0, it is implicitly also bound to any type 
  8428. T1 which is an extension of T0. However, a procedure P' (with the same name as 
  8429. P) may be explicitly bound to T1 in which case it overrides the binding of P. 
  8430. P' is considered a redefinition of P for T1. The formal parameters of P and P' 
  8431. must match (see Definition of terms). If P and T1 are exported (see section 
  8432. Declarations and scope rules) P' must be exported too. 
  8433.  
  8434. If v is a designator and P is a type-bound procedure, then v.P denotes that 
  8435. procedure P which is bound to the dynamic type of v (dynamic binding). Note, 
  8436. that this may be a different procedure than the one bound to the static type of 
  8437. v. v is passed to P's receiver according to the parameter passing rules 
  8438. specified in section Formal parameters. 
  8439.  
  8440. If r is a receiver parameter declared with type T, r.P'136 denotes the 
  8441. (redefined) procedure P bound to the base type of T. 
  8442.  
  8443. In a forward declaration of a type-bound procedure the receiver parameter must 
  8444. be of the same type as in the actual procedure declaration. The formal 
  8445. parameter lists of both declarations must match (Definition of terms). 
  8446.  
  8447. Examples: 
  8448.  
  8449.   PROCEDURE (t: Tree) Insert (node: Tree);
  8450.     VAR p, father: Tree;
  8451.   BEGIN
  8452.     p := t;
  8453.     REPEAT father := p;
  8454.       IF node.key = p.key THEN RETURN END;
  8455.       IF node.key < p.key THEN p := p.left
  8456.       ELSE p := p.right
  8457.       END
  8458.     UNTIL p = NIL;
  8459.     IF node.key < father.key THEN father.left := node
  8460.     ELSE father.right := node
  8461.     END;
  8462.     node.left := NIL;
  8463.     node.right := NIL
  8464.   END Insert;
  8465.  
  8466.   PROCEDURE (t: CenterTree) Insert (node: Tree);
  8467.     (*redefinition*)
  8468.   BEGIN
  8469.     WriteInt(node(CenterTree).width);
  8470.     t.Insert^(node)
  8471.     (* calls the Insert procedure bound to Tree *)
  8472.   END Insert;
  8473.  
  8474.  
  8475. ΓòÉΓòÉΓòÉ 16.10.3. Predeclared procedures ΓòÉΓòÉΓòÉ
  8476.  
  8477. The following table lists the predeclared procedures. Some are generic 
  8478. procedures, i.e. they apply to several types of operands. v stands for a 
  8479. variable, x and n for expressions, and T for a type. 
  8480. Function procedures 
  8481.  
  8482.  ENTIER(x) LONGREAL  =2.8cm =4.4cm 
  8483.  
  8484. The appearance of the following table is a known problem and will be improved 
  8485. in the final release. 
  8486.  
  8487. pppp Name | Argument type | Result type | Function 
  8488.  | 
  8489.  ABS(x) | numeric type | type of x | absolute value 
  8490.  ASH(x,n) | x,n: integer type | LONGINT | arithmetic shift (x*2n) 
  8491.  
  8492. The appearance of the following table is a known problem and will be improved 
  8493. in the final release. 
  8494.  
  8495. pppp CAP(x) | CHAR | CHAR | x is letter: corresponding capital letter 
  8496.  CHR(x) | integer type | CHAR | character with ordinal number x 
  8497.  ENTIER(x)| real type | LONGINT | largest integer not greater than x 
  8498.  LEN(v,n) | v: array; n: integer const. | LONGINT | length of v in dimension n 
  8499. (first dimension = 0) 
  8500.  
  8501. The appearance of the following table is a known problem and will be improved 
  8502. in the final release. 
  8503.  
  8504. pppp LEN(v) | v: array | LONGINT | the same as LEN(v,0) 
  8505.  LONG(x) | SHORTINT | INTEGER | identity 
  8506.  | INTEGER | LONGINT 
  8507.  | REAL | LONGREAL 
  8508.  
  8509. The appearance of the following table is a known problem and will be improved 
  8510. in the final release. 
  8511.  
  8512. pppp MAX(T) | T = basic type | T | maximum value of type T 
  8513.  | T = SET | INTEGER | maximum element of a set 
  8514.  MIN(T) | T = basic type | T | minimum value of type T 
  8515.  | T = SET | INTEGER | 0 
  8516.  ODD(x) | integer type | BOOLEAN | x MOD 2 = 1 
  8517.  ORD(x) | CHAR | INTEGER | ordinal number of x 
  8518.  
  8519. The appearance of the following table is a known problem and will be improved 
  8520. in the final release. 
  8521.  
  8522. pppp SHORT(x) | LONGINT | INTEGER | identity 
  8523.  | INTEGER | SHORTINT | identity 
  8524.  | LONGREAL | REAL | identity (truncation possible) 
  8525.  SIZE(T) | any type | integer | number of bytes required by T 
  8526.  
  8527. Proper procedures 
  8528.  
  8529.  NEW(v,x0,...,xn)  =4.4cm =4.2cm 
  8530.  
  8531. The appearance of the following table is a known problem and will be improved 
  8532. in the final release. 
  8533.  
  8534. ppp Name | Argument types | Function 
  8535.  | 
  8536.  ASSERT(x) | x: Boolean expression | terminate program execution if not x 
  8537.  ASSERT(x,n) | x: Boolean expression; n: integer constant | terminate program 
  8538. execution if not x 
  8539.  
  8540. The appearance of the following table is a known problem and will be improved 
  8541. in the final release. 
  8542.  
  8543. ppp COPY(x,v) | x: character array, string; v: character array | v := x 
  8544.  DEC(v) | integer type | v := v - 1 
  8545.  DEC(v,n) | v, n: integer type | v := v - n 
  8546.  
  8547. The appearance of the following table is a known problem and will be improved 
  8548. in the final release. 
  8549.  
  8550. ppp EXCL(v,x) | v: SET; x: integer type | v := v - x 
  8551.  HALT(n) | integer constant | terminate program execution 
  8552.  
  8553. The appearance of the following table is a known problem and will be improved 
  8554. in the final release. 
  8555.  
  8556. ppp INC(v) | integer type | v := v + 1 
  8557.  INC(v,n) | v, n: integer type | v := v + n 
  8558.  INCL(v,x) | v: SET; x: integer type | v := v + x 
  8559.  
  8560. The appearance of the following table is a known problem and will be improved 
  8561. in the final release. 
  8562.  
  8563. ppp NEW(v) | pointer to record or fixed array | allocate v'136 
  8564.  NEW(v,x0,...,xn) | v: pointer to open array; xi: integer type | allocate v'136 
  8565. with lengths x0.. xn 
  8566.  
  8567. COPY allows the assignment of a string or a character array containing a 
  8568. terminating 0X to another character array. If necessary, the assigned value is 
  8569. truncated to the target length minus one. The target will always contain 0X as 
  8570. a terminator. In ASSERT(x,n) and HALT(n), the interpretation of n is left to 
  8571. the underlying system implementation. 
  8572.  
  8573.  
  8574. ΓòÉΓòÉΓòÉ 16.11. Modules ΓòÉΓòÉΓòÉ
  8575.  
  8576. A module is a collection of declarations of constants, types, variables, and 
  8577. procedures, together with a sequence of statements for the purpose of assigning 
  8578. initial values to the variables. A module constitutes a text that is compilable 
  8579. as a unit. 
  8580.  
  8581.   Module     = MODULE ident ";" [ImportList]
  8582.                DeclarationSequence
  8583.                [ BEGIN StatementSequence ]
  8584.                END ident ".".
  8585.   ImportList = IMPORT Import {"," Import} ";".
  8586.   Import     = [ident ":="] ident.
  8587.  
  8588. The import list specifies the names of the imported modules. If a module A is 
  8589. imported by a module M and A exports an identifier x, then x is referred to as 
  8590. A.x within M. If A is imported as B := A, the object x is referenced as B.x. 
  8591. This allows short alias names in qualified identifiers. A module must not 
  8592. import itself. Identifiers that are to be exported (i.e. that are to be visible 
  8593. in client modules) must be marked by an export mark in their declaration (see 
  8594. section Declarations and scope rules). 
  8595.  
  8596. The statement sequence following the symbol BEGIN is executed when the module 
  8597. is added to a system (loaded), which is done after the imported modules have 
  8598. been loaded. It follows that cyclic import of modules is illegal. Individual 
  8599. (parameterless and exported) procedures can be activated from the system, and 
  8600. these procedures serve as commands. 
  8601.  
  8602. MODULE Trees;
  8603. (* exports:
  8604.   Tree, Node, Insert, Search, Write, NewTree
  8605. *)
  8606. (* exports read-only: Node.name *)
  8607. IMPORT Texts, Oberon;
  8608. TYPE
  8609.   Tree* = POINTER TO Node;
  8610.   Node* = RECORD
  8611.     name-: POINTER TO ARRAY OF CHAR;
  8612.     left, right: Tree
  8613.   END;
  8614.  
  8615. VAR w: Texts.Writer;
  8616.  
  8617. PROCEDURE (t: Tree) Insert* (name: ARRAY OF CHAR);
  8618.   VAR p, father: Tree;
  8619. BEGIN
  8620.   p := t;
  8621.   REPEAT father := p;
  8622.     IF name = p.name^ THEN RETURN END;
  8623.     IF name < p.name^ THEN p := p.left
  8624.     ELSE p := p.right
  8625.     END
  8626.   UNTIL p = NIL;
  8627.   NEW(p); p.left := NIL; p.right := NIL;
  8628.   NEW(p.name,LEN(name)+1);
  8629.   COPY(name,p.name^);
  8630.   IF name < father.name^ THEN father.left := p
  8631.   ELSE father.right := p
  8632.   END;
  8633. END Insert;
  8634.  
  8635. PROCEDURE (t: Tree) Search* (name: ARRAY OF CHAR): Tree;
  8636.   VAR p: Tree;
  8637. BEGIN
  8638.   p := t;
  8639.   WHILE (p # NIL) & (name # p.name^) DO
  8640.     IF name = p.name^ THEN p := p.left
  8641.     ELSE p := p.right
  8642.     END
  8643.   END;
  8644.   RETURN p
  8645. END Search;
  8646.  
  8647. PROCEDURE (t: Tree) Write*;
  8648. BEGIN
  8649.   IF t.left # NIL THEN t.left.Write END;
  8650.   Texts.WriteString(w, t.name^);
  8651.   Texts.WriteLn(w);
  8652.   Texts.Append(Oberon.Log, w.buf);
  8653.   IF t.right # NIL THEN t.right.Write END
  8654. END Write;
  8655.  
  8656. PROCEDURE NewTree* (): Tree;
  8657.   VAR t: Tree;
  8658. BEGIN
  8659.   NEW(t); NEW(t.name, 1);
  8660.   t.name[0] := 0X;
  8661.   t.left := NIL; t.right := NIL;
  8662.   RETURN t
  8663. END NewTree;
  8664.  
  8665. BEGIN
  8666.   Texts.OpenWriter(w)
  8667. END Trees.
  8668.  
  8669.  
  8670. ΓòÉΓòÉΓòÉ 16.12. Definition of terms ΓòÉΓòÉΓòÉ
  8671.  
  8672. The appearance of the following table is a known problem and will be improved 
  8673. in the final release. 
  8674.  
  8675.  Integer typeshahaha  Integer types  SHORTINT, INTEGER, LONGINT 
  8676.  Real types  REAL, LONGREAL 
  8677.  Numeric types  integer types, real types 
  8678.  
  8679. Same types 
  8680.  
  8681. Two variables a and b with types Ta and Tb are of the same type if 
  8682.  
  8683.    1. Ta and Tb are both denoted by the same type identifier, or 
  8684.  
  8685.    2. Ta is declared to equal Tb in a type declaration of the form Ta = Tb, or 
  8686.  
  8687.    3. a and b appear in the same identifier list in a variable, record field, 
  8688.       or formal parameter declaration and are not open arrays. 
  8689.  
  8690.  Equal types 
  8691.  
  8692.  Two types Ta and Tb are equal if 
  8693.  
  8694.    1. Ta and Tb are the same type, or 
  8695.  
  8696.    2. Ta and Tb are open array types with equal element types, or 
  8697.  
  8698.    3. Ta and Tb are procedure types whose formal parameter lists match. 
  8699.  
  8700.  Type inclusion 
  8701.  
  8702.  Numeric types include (the values of) smaller numeric types according to the 
  8703.  following hierarchy  LONGREAL ?REAL ?LONGINT ?INTEGER ?SHORTINT 
  8704.  Type extension (base type) 
  8705.  
  8706.  Given a type declaration Tb = RECORD (Ta)... END, Tb is a direct extension of 
  8707.  Ta, and Ta is a direct base type of Tb. A type Tb is an extension of a type Ta 
  8708.  (Ta is a base type of Tb) if 
  8709.  
  8710.    1. Ta and Tb are the same types, or 
  8711.  
  8712.    2. Tb is a direct extension of an extension of Ta 
  8713.  
  8714.  If Pa = POINTER TO Ta and Pb = POINTER TO Tb, Pb is an extension of Pa (Pa is 
  8715.  a base type of Pb) if Tb is an extension of Ta. 
  8716.  Assignment compatible 
  8717.  
  8718.  An expression e of type Te is assignment compatible with a variable v of type 
  8719.  Tv if one of the following conditions hold: 
  8720.  
  8721.    1. Te and Tv are the same type; 
  8722.  
  8723.    2. Te and Tv are numeric types and Tv includes Te; 
  8724.  
  8725.    3. Te and Tv are record types and Te is an extension of Tv and the dynamic 
  8726.       type of v is Tv ; 
  8727.  
  8728.    4. Te and Tv are pointer types and Te is an extension of Tv; 
  8729.  
  8730.    5. Tv is a pointer or a procedure type and e is NIL; 
  8731.  
  8732.    6. Tv is ARRAY n OF CHAR, e is a string constant with m characters, and m < 
  8733.       n; 
  8734.  
  8735.    7. Tv is a procedure type and e is the name of a procedure whose formal 
  8736.       parameters match those of Tv. 
  8737.  
  8738.  Array compatible 
  8739.  
  8740.  An actual parameter a of type Ta is array compatible with a formal parameter f 
  8741.  of type Tf if 
  8742.  
  8743.    1. Tf and Ta are the same type, or 
  8744.  
  8745.    2. Tf is an open array, Ta is any array, and their element types are array 
  8746.       compatible, or 
  8747.  
  8748.    3. Tf is ARRAY OF CHAR and a is a string. 
  8749.  
  8750.  Expression compatible 
  8751.  
  8752.  For a given operator, the types of its operands are expression compatible if 
  8753.  they conform to the following table (which shows also the result type of the 
  8754.  expression). Character arrays to be compared must contain 0X as a terminator. 
  8755.  Type T1 must be an extension of type T0: 
  8756.  
  8757.   compact = = < <= > >=  =2.7cm =3.7cm 
  8758.  
  8759.  The appearance of the following table is a known problem and will be improved 
  8760.  in the final release. 
  8761.  
  8762.  pppp operator | first operand | second operand | result type 
  8763.   + - * | numeric | numeric | smallest numeric type including both operands 
  8764.   / | numeric | numeric | smallest real type including both operands 
  8765.   + - * / | SET | SET | SET 
  8766.  
  8767.  The appearance of the following table is a known problem and will be improved 
  8768.  in the final release. 
  8769.  
  8770.  pppp DIV MOD | integer | integer | smallest integer type including both 
  8771.  operands 
  8772.   OR & ~ | BOOLEAN | BOOLEAN | BOOLEAN 
  8773.  
  8774.  The appearance of the following table is a known problem and will be improved 
  8775.  in the final release. 
  8776.  
  8777.  pppp = # < <= > >= | numeric | numeric | BOOLEAN 
  8778.   | CHAR | CHAR | BOOLEAN 
  8779.   | character array, string | character array, string | BOOLEAN 
  8780.   = # | BOOLEAN | BOOLEAN | BOOLEAN 
  8781.   | SET | SET | BOOLEAN 
  8782.   | NIL, POINTER TO T0 or T1 | NIL, POINTER TO T0 or T1 | BOOLEAN 
  8783.   | procedure type T, NIL | procedure type T, NIL | BOOLEAN 
  8784.   IN | integer | SET | BOOLEAN 
  8785.   IS | pointer | pointer | BOOLEAN 
  8786.   | record | record | BOOLEAN 
  8787.  
  8788.  
  8789. ΓòÉΓòÉΓòÉ 16.12.1. Matching formal parameter lists ΓòÉΓòÉΓòÉ
  8790.  
  8791. Two formal parameter lists match if 
  8792.  
  8793.    1. they have the same number of parameters, and 
  8794.  
  8795.    2. they have either the same function result type or none, and 
  8796.  
  8797.    3. parameters at corresponding positions have equal types, and 
  8798.  
  8799.    4. parameters at corresponding positions are both either value or variable 
  8800.       parameters. 
  8801.  
  8802.  
  8803. ΓòÉΓòÉΓòÉ 16.13. Syntax of Oberon-2 ΓòÉΓòÉΓòÉ
  8804.  
  8805. Module      = MODULE ident ";" [ImportList] DeclSeq
  8806.              [BEGIN StatementSeq] END ident ".".
  8807. ImportList  = IMPORT [ident ":="] ident
  8808.               {"," [ident ":="] ident} ";".
  8809. DeclSeq     =  { CONST {ConstDecl ";" }
  8810.             | TYPE {TypeDecl ";"}
  8811.             | VAR {VarDecl ";"}} {ProcDecl ";"
  8812.             | ForwardDecl ";"}.
  8813. ConstDecl   = IdentDef "=" ConstExpr.
  8814. TypeDecl    = IdentDef "=" Type.
  8815. VarDecl     = IdentList ":" Type.
  8816. ProcDecl    = PROCEDURE [Receiver] IdentDef
  8817.               [FormalPars] ";" DeclSeq [BEGIN
  8818.               StatementSeq] END ident.
  8819. ForwardDecl = PROCEDURE "^" [Receiver] IdentDef
  8820.               [FormalPars].
  8821. FormalPars  = "(" [FPSection {";" FPSection}] ")"
  8822.               [":" Qualident].
  8823. FPSection   = [VAR] ident {"," ident} ":" Type.
  8824. Receiver    = "(" [VAR] ident ":" ident ")".
  8825. Type        = Qualident
  8826.             | ARRAY [ConstExpr {"," ConstExpr}] OF Type
  8827.             | RECORD ["("Qualident")"] FieldList
  8828.               {";" FieldList} END
  8829.             | POINTER TO Type
  8830.             | PROCEDURE [FormalPars]
  8831. FieldList   = [IdentList ":" Type].
  8832. StatementSeq= Statement {";" Statement}.
  8833. Statement   = [Designator ":=" Expr
  8834.             | Designator ["(" [ExprList] ")"]
  8835.             | IF Expr THEN StatementSeq
  8836.              {ELSIF Expr THEN StatementSeq}
  8837.              [ELSE StatementSeq] END
  8838.             | CASE Expr OF Case {"|" Case}
  8839.               [ELSE StatementSeq] END
  8840.             | WHILE Expr DO StatementSeq END
  8841.             | REPEAT StatementSeq UNTIL Expr
  8842.             | FOR ident ":=" Expr TO Expr
  8843.               [BY ConstExpr] DO StatementSeq END
  8844.             | LOOP StatementSeq END
  8845.             | WITH Guard DO StatementSeq
  8846.              {"|" Guard DO StatementSeq}
  8847.               [ELSE StatementSeq] END
  8848.             | EXIT
  8849.             | RETURN [Expr]].
  8850. Case        = [CaseLabels {"," CaseLabels}
  8851.               ":" StatementSeq].
  8852. CaseLabels  = ConstExpr [".." ConstExpr].
  8853. Guard       = Qualident ":" Qualident.
  8854. ConstExpr   = Expr.
  8855. Expr        = SimpleExpr [Relation SimpleExpr].
  8856. SimpleExpr  = ["+" | "-"] Term {AddOp Term}.
  8857. Term        = Factor {MulOp Factor}.
  8858. Factor      = Designator ["(" [ExprList] ")"]
  8859.             | number | character | string | NIL
  8860.             | Set | "(" Expr ")" | " ~ " Factor.
  8861. Set         = "{" [Element {"," Element}] "}".
  8862. Element     = Expr [".." Expr].
  8863. Relation    = "=" | "#" | "<" | "<=" | ">" | ">="
  8864.             | IN | IS.
  8865. AddOp       = "+" | "-" | OR.
  8866. MulOp       = " * " | "/" | DIV | MOD | "&".
  8867. Designator  = Qualident {"." ident | "[" ExprList "]"
  8868.             |  "^" | "(" Qualident ")"}.
  8869. ExprList    = Expr {"," Expr}.
  8870. IdentList   = IdentDef {"," IdentDef}.
  8871. Qualident   = [ident "."] ident.
  8872. IdentDef    = ident [" * " | "-"].
  8873.  
  8874.  
  8875. ΓòÉΓòÉΓòÉ 16.14. The module SYSTEM ΓòÉΓòÉΓòÉ
  8876.  
  8877. The module SYSTEM contains certain types and procedures that are necessary to 
  8878. implement low-level operations particular to a given computer and/or 
  8879. implementation. These include for example facilities for accessing devices that 
  8880. are controlled by the computer, and facilities to break the type compatibility 
  8881. rules otherwise imposed by the language definition. It is strongly recommended 
  8882. to restrict their use to specific modules (called low-level modules). Such 
  8883. modules are inherently non-portable, but easily recognized due to the 
  8884. identifier SYSTEM appearing in their import list. The following specifications 
  8885. hold for the implementation of Oberon-2 on the Ceres computer. 
  8886.  
  8887. Module SYSTEM exports a type BYTE with the following characteristics: Variables 
  8888. of type CHAR or SHORTINT can be assigned to variables of type BYTE. If a formal 
  8889. variable parameter is of type ARRAY OF BYTE then the corresponding actual 
  8890. parameter may be of any type. 
  8891.  
  8892. Another type exported by module SYSTEM is the type PTR. Variables of any 
  8893. pointer type may be assigned to variables of type PTR. If a formal variable 
  8894. parameter is of type PTR, the actual parameter may be of any pointer type. 
  8895.  
  8896. The procedures contained in module SYSTEM are listed in the following tables. 
  8897. Most of them correspond to single instructions compiled as in-line code. For 
  8898. details, the reader is referred to the processor manual. v stands for a 
  8899. variable, x, y, a, and n for expressions, and T for a type. 
  8900. Function procedures 
  8901.  
  8902.  ROT(w,w) BOOLEAN =2.8cm =4.4cm 
  8903.  
  8904. The appearance of the following table is a known problem and will be improved 
  8905. in the final release. 
  8906.  
  8907. pppp Name | Argument types | Result type | Function 
  8908.  | 
  8909.  ADR(v) | any | LONGINT | address of variable v 
  8910.  BIT(a,n) | a: LONGINT n: integer | BOOLEAN | bit n of Mem[a] 
  8911.  CC(n) | integer constant | BOOLEAN | condition n (0?n?15) 
  8912.  
  8913. The appearance of the following table is a known problem and will be improved 
  8914. in the final release. 
  8915.  
  8916. pppp LSH(x,n) | x: integer, CHAR, BYTE; n: integer | type of x | logical shift 
  8917.  ROT(x,n) | x: integer, CHAR, BYTE; n: integer | type of x | rotation 
  8918.  VAL(T,x) | T, x: any type | T | x interpreted as of type T 
  8919.  
  8920. Proper procedures 
  8921.  
  8922.  MOVE(a0,a1,n) =4.4cm =4.2cm 
  8923.  
  8924. The appearance of the following table is a known problem and will be improved 
  8925. in the final release. 
  8926.  
  8927. ppp Name | Argument types | Function 
  8928.  | 
  8929.  GET(a,v) | a: LONGINT; v: any basic type, pointer, procedure type | v := 
  8930. Mem[a] 
  8931.  PUT(a,x) | a: LONGINT; x: any basic type, pointer, procedure type | Mem[a] :=x 
  8932.  
  8933. The appearance of the following table is a known problem and will be improved 
  8934. in the final release. 
  8935.  
  8936. ppp GETREG(n,v) | n: integer constant; v: any basic type, pointer, procedure 
  8937. type | v := Register n 
  8938.  PUTREG(n,x) | n: integer constant; x: any basic type, pointer, procedure type 
  8939. | Register n := x 
  8940.  
  8941. The appearance of the following table is a known problem and will be improved 
  8942. in the final release. 
  8943.  
  8944. ppp MOVE(a0,a1,n) | a0, a1: LONGINT; n: integer | Mem[a1..a1+n-1] := 
  8945. Mem[a0..a0+n-1] 
  8946.  NEW(v,n) | v: any pointer; n: integer | allocate storage block of n bytes 
  8947. assign its address to v 
  8948.