samples.txt                      Copyright (c) 1994,96 xTech Ltd
----------------------------------------------------------------

                     Description of Samples
                     ----------------------

We assume here, that XDS was properly installed, the working
directory was created and the  "mkwrkdir"  file was executed
(See readme.1st).

All examples in this text is provided for OS/2 version.
See your readme.1st file for the information concerning
your distribution.

The "samples" directory contains the following subdirectories
and files:
        simple   - simple samples
        dhry     - dhrystone test (note: a single module dhrystone
                   test is placed to the "simple" directory)
                   See also "bench.txt".
        nodes    - an Oberon-2 example, illustrating the using
                   of Oberon run-time support.
        pmhello  - an example of Program Manager application, written
                   in Modula-2. Rewritten STDWND example from OS/2
                   Developer's Toolkit.
        cset     - provides an example of mixed project, which
                   consists of Modula-2 and C units. 
                   IBM's C compiler used.
        watcom   - provides an example of mixed project, which
                   consists of Modula-2 and C units.
                   WATCOM's C compiler used.
        *.prj     - XDS project files for samples .
       
samples\simple
--------------

All  the  samples  on this directory consists of the only module.
Tests are written in Modula-2 and in Oberon-2. In these tests the
specific features  of  Oberon-2 are not used.

The following tests are provided:
        hello.mod       Hello, World       (Modula-2)
        hello.ob2       Hello, World       (Oberon-2)

        hisdemo.mod     History demo       (Modula-2) (See hisdemo.prj)

        ackerman.ob2    Ackermann function (Oberon-2)

        exp.ob2         Calculate exponent (Oberon-2)
        exp.mod         Calculate exponent (Modula-2)

        self.ob2        Print self text    (Oberon-2)

        sieve.ob2       Prime numbers      (Oberon-2)
        sieve.mod       Prime numbers      (Modula-2)

        fact.mod        Factorial          (Modula-2)

        halt.mod        Termination        (Modula-2)
        term.mod        Termination        (Modula-2)
        except.mod      Exceptions         (Modula-2)

	dry.mod	 	Dhrystone	   (Modula-2)
		        (single module)
	whet.mod   	Whetstone	   (Modula-2)

The  redirection  file  "xc.red"  contains  path  to  the  SIMPLE
directory. To get an executable program from a test, invoke "xc"
in the make mode passing the name of the test:

        xc hello.mod =make
or
        xc hello.ob2 =make

After that run the program:

        hello


Another way is to compile a test separately, invoking "xc" with
the name of the test:

        xc hello.mod
or
        xc hello.ob2

To build the program use the xl.cmd file.

	xl hello

After that run the program:

        hello

For "hisdemo" sample, use:

        xc hisdemo.mod =make +genhistory

To see the stack of procedure calls ("execution history") use
his utility (C:\XDS\BIN\his.exe):

        his

It searches for "errinfo.xds" file and appropriate map file to
produce the list of procedure calls. Every item of the list consists
of a source file name, a line number and optionaly a procedure name.

samples\dhry
------------

The "dhry" directory contains two variants of well known Dhrystone
test:
        puredhry.mod
        timedhry.mod

Both tests imports "dry1" and "dry2" libraries.

To prepare executable use PROJECT operation mode. The working directory
contains the project file "puredhry.prj".

        xc =p puredhry

A response file "puredhry.rsp" will be created after compilation
and "link386" will be called to link the program.
If you have not enough memory, run

	link386 @puredhry.rsp

samples\nodes
-------------

The "nodes" subdirectory contains the following files, constituting
the Oberon-2 program:

        Nodes.ob2       - definition of abstract Node class
        Echo.ob2        - concrete Node extension
        GenEcho.ob2     - concrete Node extension
        Commands.ob2    - concrete Node extension
        Types.ob2       - concrete Node extension
        runme.ob2       - the top-level module

To build the program invoke:

        xc =p nodes.prj

The  "Nodes" module defines an abstract object (Node). Objects of
this  type  are  linked  in  the  list.  The  module "Nodes" also
implement  the  command  monitor  ("Loop"  procedure). The "Loop"
procedure  reads an input from keyboard and then passes the input
to  the  current  node,  or  if  the  input  line starts from "."
executes some standard action.

The  module  "runme"  imports  modules defining the extensions of
type  Node  (concrete  classes),  inserts it in the list and then
call "Nodes.Loop".

Nodes.Node extensions:
----------------------

"Echo"     - implements a node which prints its input to terminal.

"GenEcho"  - if the number N is specified in the input line
             creates "N" examples of the "Echo" Node.

"Commands" - provides facilities to call commands (exported
             parameterless procedures) in the form:
                ModuleName.ProcedureName
             Also implements operations to enumerate all modules
             in the program and all commands in the given module.

"Types"    - provides facilities to allocate an object by the
             given name in the form:
                ModuleName.RecordTypeName


Modules   "Types"   and   "Commands"  illustrates  the  using  of
meta-language   facilities,   including  the  command  calls  and
creating an object by its type name.

It is important to note, that the XDS does not support the
dynamic  loading  of  the modules. You can use commands and types
from the modules which are already linked in the program.

samples\pmhello
----------------

The directory contains:
        pmhello.mod    - Modula-2 module
        pmhello.res    - resource file

To build the program, run
        xc pmhello =p

This sample was taken from OS/2 Developer's Toolkit and rewritten 
from C to Modula-2. It shows how to write Presentation Manager 
application in Modula or Oberon. Definition module OS2.def was
derived from header files *.H of the same Toolkit.
Now this file contains almost all API definition but it still under
work so you may find some lacks and mistranslations.

If you are going to write your PM application now, take the
following in the consideration:

1) If OS2.def does not contain a definition of function that
you need, you can use external procedure specification,
for instance:

PROCEDURE ["SysCall"] / DosBeep(freq, dur: CARDINAL): OS2.APIRET;

2) Standard os2386.lib should be linked to all PM applications instead
minimal interface library os2min.lib, which provides access to restricted
number of API calls only.


samples\cset
------------

The directory contains:
        cmain.c         - main module of the program (C)
        m2test.def      - definition module
        m2test.mod      - implementation module
        m2test.h        - header file (manually written)
        stdio.def       - interface to <stdio.h>
        cset.tem        - template file 

The sample shows how to write mixed project, i.e. projects written 
partially in C and partially in Modula or Oberon. To compile 
this test, the IBM's CSET should be properly installed. 
For such a project the CSET library should be used.

To build the program, run:

        xc cset =p

Take in attention that XDS compiler does not support _Optlink calling
conventions yet. So you can not call from Modula-2/Oberon-2 directly
those functions of standard CSET library which use such conventions.
To call _Optlink C function you must provide an intermediate C function
with _SysCall conventions.

samples\watcom
--------------

The directory contains:
        cmain.c         - main module of the program (C)
        m2test.def      - definition module
        m2test.mod      - implementation module
        m2test.h        - header file (manually written)
        stdio.def       - interface to <stdio.h>
        watcom.tem      - template file 

The samples show how to write mixed project, i.e. projects written 
partially in C and partially in Modula or Oberon. To compile 
this test, the Watcom C should be properly installed. For such 
a project the Watcom linker and Watcom libraries should be used.

To build the program, run:
        xc watcom =p

--------------------------------

Note: stdio.def provides an interface to <stdio.h>. Not all 
function are available or properly tested. This file is not an 
official part of XDS distribution.

If you are going to write mixed projects, use cmain.c as an 
example. XDS run-time support should be properly installed.


                        [end of document]
