home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / xco212p.zip / DOC / SAMPLES.TXT < prev    next >
Text File  |  1996-03-05  |  9KB  |  271 lines
  1. samples.txt                      Copyright (c) 1994,96 xTech Ltd
  2. ----------------------------------------------------------------
  3.  
  4.                      Description of Samples
  5.                      ----------------------
  6.  
  7. We assume here, that XDS was properly installed, the working
  8. directory was created and the  "mkwrkdir"  file was executed
  9. (See readme.1st).
  10.  
  11. All examples in this text is provided for OS/2 version.
  12. See your readme.1st file for the information concerning
  13. your distribution.
  14.  
  15. The "samples" directory contains the following subdirectories
  16. and files:
  17.         simple   - simple samples
  18.         dhry     - dhrystone test (note: a single module dhrystone
  19.                    test is placed to the "simple" directory)
  20.                    See also "bench.txt".
  21.         nodes    - an Oberon-2 example, illustrating the using
  22.                    of Oberon run-time support.
  23.         pmhello  - an example of Program Manager application, written
  24.                    in Modula-2. Rewritten STDWND example from OS/2
  25.                    Developer's Toolkit.
  26.         cset     - provides an example of mixed project, which
  27.                    consists of Modula-2 and C units. 
  28.                    IBM's C compiler used.
  29.         watcom   - provides an example of mixed project, which
  30.                    consists of Modula-2 and C units.
  31.                    WATCOM's C compiler used.
  32.         *.prj     - XDS project files for samples .
  33.        
  34. samples\simple
  35. --------------
  36.  
  37. All  the  samples  on this directory consists of the only module.
  38. Tests are written in Modula-2 and in Oberon-2. In these tests the
  39. specific features  of  Oberon-2 are not used.
  40.  
  41. The following tests are provided:
  42.         hello.mod       Hello, World       (Modula-2)
  43.         hello.ob2       Hello, World       (Oberon-2)
  44.  
  45.         hisdemo.mod     History demo       (Modula-2) (See hisdemo.prj)
  46.  
  47.         ackerman.ob2    Ackermann function (Oberon-2)
  48.  
  49.         exp.ob2         Calculate exponent (Oberon-2)
  50.         exp.mod         Calculate exponent (Modula-2)
  51.  
  52.         self.ob2        Print self text    (Oberon-2)
  53.  
  54.         sieve.ob2       Prime numbers      (Oberon-2)
  55.         sieve.mod       Prime numbers      (Modula-2)
  56.  
  57.         fact.mod        Factorial          (Modula-2)
  58.  
  59.         halt.mod        Termination        (Modula-2)
  60.         term.mod        Termination        (Modula-2)
  61.         except.mod      Exceptions         (Modula-2)
  62.  
  63.     dry.mod         Dhrystone       (Modula-2)
  64.                 (single module)
  65.     whet.mod       Whetstone       (Modula-2)
  66.  
  67. The  redirection  file  "xc.red"  contains  path  to  the  SIMPLE
  68. directory. To get an executable program from a test, invoke "xc"
  69. in the make mode passing the name of the test:
  70.  
  71.         xc hello.mod =make
  72. or
  73.         xc hello.ob2 =make
  74.  
  75. After that run the program:
  76.  
  77.         hello
  78.  
  79.  
  80. Another way is to compile a test separately, invoking "xc" with
  81. the name of the test:
  82.  
  83.         xc hello.mod
  84. or
  85.         xc hello.ob2
  86.  
  87. To build the program use the xl.cmd file.
  88.  
  89.     xl hello
  90.  
  91. After that run the program:
  92.  
  93.         hello
  94.  
  95. For "hisdemo" sample, use:
  96.  
  97.         xc hisdemo.mod =make +genhistory
  98.  
  99. To see the stack of procedure calls ("execution history") use
  100. his utility (C:\XDS\BIN\his.exe):
  101.  
  102.         his
  103.  
  104. It searches for "errinfo.xds" file and appropriate map file to
  105. produce the list of procedure calls. Every item of the list consists
  106. of a source file name, a line number and optionaly a procedure name.
  107.  
  108. samples\dhry
  109. ------------
  110.  
  111. The "dhry" directory contains two variants of well known Dhrystone
  112. test:
  113.         puredhry.mod
  114.         timedhry.mod
  115.  
  116. Both tests imports "dry1" and "dry2" libraries.
  117.  
  118. To prepare executable use PROJECT operation mode. The working directory
  119. contains the project file "puredhry.prj".
  120.  
  121.         xc =p puredhry
  122.  
  123. A response file "puredhry.rsp" will be created after compilation
  124. and "link386" will be called to link the program.
  125. If you have not enough memory, run
  126.  
  127.     link386 @puredhry.rsp
  128.  
  129. samples\nodes
  130. -------------
  131.  
  132. The "nodes" subdirectory contains the following files, constituting
  133. the Oberon-2 program:
  134.  
  135.         Nodes.ob2       - definition of abstract Node class
  136.         Echo.ob2        - concrete Node extension
  137.         GenEcho.ob2     - concrete Node extension
  138.         Commands.ob2    - concrete Node extension
  139.         Types.ob2       - concrete Node extension
  140.         runme.ob2       - the top-level module
  141.  
  142. To build the program invoke:
  143.  
  144.         xc =p nodes.prj
  145.  
  146. The  "Nodes" module defines an abstract object (Node). Objects of
  147. this  type  are  linked  in  the  list.  The  module "Nodes" also
  148. implement  the  command  monitor  ("Loop"  procedure). The "Loop"
  149. procedure  reads an input from keyboard and then passes the input
  150. to  the  current  node,  or  if  the  input  line starts from "."
  151. executes some standard action.
  152.  
  153. The  module  "runme"  imports  modules defining the extensions of
  154. type  Node  (concrete  classes),  inserts it in the list and then
  155. call "Nodes.Loop".
  156.  
  157. Nodes.Node extensions:
  158. ----------------------
  159.  
  160. "Echo"     - implements a node which prints its input to terminal.
  161.  
  162. "GenEcho"  - if the number N is specified in the input line
  163.              creates "N" examples of the "Echo" Node.
  164.  
  165. "Commands" - provides facilities to call commands (exported
  166.              parameterless procedures) in the form:
  167.                 ModuleName.ProcedureName
  168.              Also implements operations to enumerate all modules
  169.              in the program and all commands in the given module.
  170.  
  171. "Types"    - provides facilities to allocate an object by the
  172.              given name in the form:
  173.                 ModuleName.RecordTypeName
  174.  
  175.  
  176. Modules   "Types"   and   "Commands"  illustrates  the  using  of
  177. meta-language   facilities,   including  the  command  calls  and
  178. creating an object by its type name.
  179.  
  180. It is important to note, that the XDS does not support the
  181. dynamic  loading  of  the modules. You can use commands and types
  182. from the modules which are already linked in the program.
  183.  
  184. samples\pmhello
  185. ----------------
  186.  
  187. The directory contains:
  188.         pmhello.mod    - Modula-2 module
  189.         pmhello.res    - resource file
  190.  
  191. To build the program, run
  192.         xc pmhello =p
  193.  
  194. This sample was taken from OS/2 Developer's Toolkit and rewritten 
  195. from C to Modula-2. It shows how to write Presentation Manager 
  196. application in Modula or Oberon. Definition module OS2.def was
  197. derived from header files *.H of the same Toolkit.
  198. Now this file contains almost all API definition but it still under
  199. work so you may find some lacks and mistranslations.
  200.  
  201. If you are going to write your PM application now, take the
  202. following in the consideration:
  203.  
  204. 1) If OS2.def does not contain a definition of function that
  205. you need, you can use external procedure specification,
  206. for instance:
  207.  
  208. PROCEDURE ["SysCall"] / DosBeep(freq, dur: CARDINAL): OS2.APIRET;
  209.  
  210. 2) Standard os2386.lib should be linked to all PM applications instead
  211. minimal interface library os2min.lib, which provides access to restricted
  212. number of API calls only.
  213.  
  214.  
  215. samples\cset
  216. ------------
  217.  
  218. The directory contains:
  219.         cmain.c         - main module of the program (C)
  220.         m2test.def      - definition module
  221.         m2test.mod      - implementation module
  222.         m2test.h        - header file (manually written)
  223.         stdio.def       - interface to <stdio.h>
  224.         cset.tem        - template file 
  225.  
  226. The sample shows how to write mixed project, i.e. projects written 
  227. partially in C and partially in Modula or Oberon. To compile 
  228. this test, the IBM's CSET should be properly installed. 
  229. For such a project the CSET library should be used.
  230.  
  231. To build the program, run:
  232.  
  233.         xc cset =p
  234.  
  235. Take in attention that XDS compiler does not support _Optlink calling
  236. conventions yet. So you can not call from Modula-2/Oberon-2 directly
  237. those functions of standard CSET library which use such conventions.
  238. To call _Optlink C function you must provide an intermediate C function
  239. with _SysCall conventions.
  240.  
  241. samples\watcom
  242. --------------
  243.  
  244. The directory contains:
  245.         cmain.c         - main module of the program (C)
  246.         m2test.def      - definition module
  247.         m2test.mod      - implementation module
  248.         m2test.h        - header file (manually written)
  249.         stdio.def       - interface to <stdio.h>
  250.         watcom.tem      - template file 
  251.  
  252. The samples show how to write mixed project, i.e. projects written 
  253. partially in C and partially in Modula or Oberon. To compile 
  254. this test, the Watcom C should be properly installed. For such 
  255. a project the Watcom linker and Watcom libraries should be used.
  256.  
  257. To build the program, run:
  258.         xc watcom =p
  259.  
  260. --------------------------------
  261.  
  262. Note: stdio.def provides an interface to <stdio.h>. Not all 
  263. function are available or properly tested. This file is not an 
  264. official part of XDS distribution.
  265.  
  266. If you are going to write mixed projects, use cmain.c as an 
  267. example. XDS run-time support should be properly installed.
  268.  
  269.  
  270.                         [end of document]
  271.