
PalmOS  Pascal  Compiler

Version 1.00d
2002/08/31

by Philippe GUILLOT

ph.guillot@wanadoo.fr


INTRODUCTION:
-------------

 PP is a freeware standard Pascal compiler for PalmOS. PP generates true native
68000 executable code (.PRC) from standard Pascal source code.
You can use your favorite Palm DOC editor to write your code, and either run PP
from the VFSdos console or PPShell to compile and run your program.

 Applications created by PP have all the same Palm unique registered ID 'pDOS',
which is the standard ID for all VFSdos applications. This means that your
compiled applications can be executed from either the PP shell interface, or
the VFSdos console, and you do not need to register a unique ID for them. For
more information about VFSdos, please visit the VFSdos web page.

 PP is not intended for graphical UI application development. The primary
output is a text console, and the input is either graffiti or optional keyboard.
It's mainly used to create calculation output applications, test algorithms,
or any other text based VFSDos application. Applications created by PP can be launched
with command parameters either from the VFSdos console, or the PP Shell application.

 PP has been tested on the following handhelds: Palm III, m500, m505, m515, 
Sony Clie 625, and TRGpro. PP has also been tested under the OS5 simulator and it's 
PalmOS 5.0 ready. Although PP has been tested extensively, like any other Palm 
application, it may have bugs. Please contact me for any suggestions or bug reports.


REQUIREMENTS:
-------------

- PalmOS 3.5 or greater.
- 120 k of free dynamic heap memory.
- Mathlib library (only if the program uses one the mathematical functions:
  arctan, cos, sin, log, exp or sqrt).
- VFSDos * console interface.

 * NOTE: If you wish you may use PP within the VFSdos console, instead of  PP
   Shell. VFSdos is a DOS-alike console interface for PalmOS. You can find the
   latest version of VFSdos from the following site:

     http://www.total.net/~hkonstas/vfsdos.html


DOWNLOAD:
---------

You can download the current version of PP from the following link:

  http://www.total.net/~hkonstas/pp.zip


INSTALLATION:
-------------

Distribution files:

PP.EXE:       The Pascal compiler for VFSdos.
STDIOLIB.PRC: The latest STDIO library (required).
PPSHELL.PRC:  The compiler gui shell application (if you do not use VFSdos
              on your handheld).

*.PAS:        Pascal source code samples in DOC format.

Optional files (NOT included in the distribution ZIP):

VFSDOS.PRC:   The VFSdos console.
MATHLIB.PRC:  The mathlib library for optional math operations.

 Install pp_exe.prc and the latest version of the STDIO library, StdioLib.prc.
If you are already using an older version of StdioLib, please install the
version included in this distribution zip file. You may also install
PPshell.prc if you do not have VFSdos installed on your handheld. You may
find useful to also install the pascal sample files included in the zip to get
you started. Please note that source code files are databases in DOC format,
readable by any DOC reader ( provided that they contain regular characters).



USAGE:
------

 Launch the PP Shell application and you will see the list of the sample source
code files (all in DOC format, having the .pas extension). Simply select the
file you want to compile, and press the GO button. Once the source has been
successfully compiled, select the EXECUTE button. Now you will see the list of
all the compiled PP applications. You can enter optional arguments in the text
field under the list, and press the GO button to execute your application. Use
the DEL button to delete a selected application from the list.

 If you have VFSdos installed on your handheld and will be using PP from within
the VFSdos console, you simply launch pp with the source filename as a
parameter directly from the VFSdos prompt:

   c:>pp sourcename

where 'sourcename' is the name of your application source database. This
example compiles the doc database named 'sourcename.pas'.

If the program header in your source code is:

    program exename; ...

then a PRC database named 'exename.exe' is created.

Finally, to execute your compiled application, just type it in the VFSdos
command prompt:

  c:>exename  <param n>

where <param n> are the optional application parameters (if any).

PP supports cooperation with doc editor QED. If an error occurs when compiling,
a prompt "goto error ?[y]" proposes you to launch Qed at error position.


PP  LANGUAGE FEATURES:
----------------------

 The langage syntax is compliant to the ISO 1775:1990 level 0. In particular,
it supports
- nonlocal goto,
- procedure and function as parameter,
- stardard syntax for new and dispose for pointer to record with variant.

 The conformant array schema are NOT supported.

 There is no runtime range control.

See http://pascal-central.com for a complete description and  the demo
sources for examples.


Files:

Files are stored as uncompressed doc database in binary format.
Files of char and text are readable by any doc reader. The read functions
support compressed doc.

Files other than input and output are declared in the program
parameter list are assigned to the actual parameters of the
command line.

The function reset(f) opens a file for reading which is specified in the
program parameter list.

To open a file while is not in the program parameter list, the
syntax is reset(f,name), where name is a packed array[1..n] of
char. The same convention applies to open a file for writing
using the procedure rewrite.

The (non standard) function close(f) must be called for all open files.

The standard input supports interactive mode (lazy I/O) for get procedure
and when reading characters.

Runtime error codes:
--------------------

102: Program parameter missing.
103: VFSDOSdata database not found.
105: File not open for inspection.
106: Unexpected end of file (EOF) while reading.
110: File not open for generation.
120: Invalid integer or real format.
158: Incorrect width parameter on text write.
200: Inexact result when trunc or round on a real.
201: mathlib library not found.
206: Unable to open file.
301: log or sqrt has negative parameter.
1000: Internal error (unexpected NULL handle).


Misc:
-----

- Real are 32 bit float;
- Integer are 16 bit int;
- enumerated type is 8 bit;
- array and record size is limited to 32k;
- global data storage is limited to 32k
- string constants storage is limited to 32k
- integer sets are limited to the range 0..255
- packed structured type are implemented as unpacked types.
- Functions pack and unpack currently not supported.
- Additional gotoxy(x,y) function which positions the cursor at the desired
  screen position.
- Additional textmode(mode) function which selects video mode: 1=32 cols 0=40
  cols.
- Additional clrscr() function which clears the screen.
- Character '$' starts hexadecimal representation integers.
- Underscore '_'is allowed inside identifiers.

Disclaimer:
-----------

 The PP compiler is distributed as freeware, and like any software application,
although well tested, it may contain bugs. The author cannot be held
responsible for any data loss. The user takes full responsibility for using
the program.


HISTORY:
--------

1.00d: Sept. 13th,2002: Bug Fixex, code optimization, samples.

1.00c: Sept. 7th,2002: Bug fixes, speed and code optimizations. 

1.00b: Sept. 2nd, 2002: Minor update (bug fixes, PPshell updated).

1.00a: August 31st, 2002: Initial Release.


* The PP compiler has been developped by Philippe Guillot on an Cli T625C,
  using OnBoardC, QED and RsrcEdit.

* PP Shell was written by Harry Konstas on a m505 using OnBoardC, QED and
  RsrcEdit.



Philippe GUILLOT
ph.guillot@wanadoo.fr

