
PalmOS  Pascal  Compiler

Version 2.00 (full version including native 68k and ARM code generation)
Version 1.09 (Standard VFSDos version for 68k code generation only)

2003/05/02

by Philippe GUILLOT

ph.guillot@wanadoo.fr


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

 PP  is a freeware standard Pascal compiler for PalmOS. PP generates true native
68000 or ARM 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.

 VFSDos  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 also able compile Palm graphical UI applications, hack extensions, shared
libraries and multi segment applications (see further and provided samples).

 PP  has  been  tested  on  the following handhelds: Palm III, m500, m505, m515, 
Sony  Clie T625, TRGpro and Tungsten T. 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. PalmOS >=5.0 is required to execute armlet.
- 140 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://pages.total.net/~hkonstas/vfsdos.html


DOWNLOAD:
---------

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

  http://pages.total.net/~hkonstas/pp.html


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

Distribution files:

PP_EXE.PRC:   The Standard Pascal compiler for VFSdos, version 1.09.

ppLight/PP_EXE.PRC A version of the compiler for low memory device such as m100.

ppARM/PP_EXE.PRC  The full version 2.00 for also compiling armlet on OS5
              devices.

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.

PgmPP.zip     Laurent Duveau's demo files

Optional files (NOT included in the distribution ZIP):

VFSDOS.PRC:   The Harry Konstas VFSdos console.

MATHLIB.PRC:  The mathlib library required for optional math operations.

QED.PRC:      The doc editor (shareware) available at http://www.qland.de/qed/

  Install one of the "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 uncompressed DOC
format, readable by any DOC reader.

  If a message "unable to initialize" appears, you may try to install the file
included in the folder ppLight. This version has a lower memory requirement.
In counter part, some huge source may not compile and the executable sise is
limited to 24 ko.

  The version 2.00 included in the ppArm forlder has the same features as the
standard PP and in addition, it may compile native armlet (using the directive
{$armlet xxxx,yyyy,zzzz,nnn} similar to the {$code...} directive described in
the sequel). It support most Pascal features except standard io and real
transcendental functions (sin, cos, etc.) which are not yet implemented. The
compiler runs on 68k devices, but arm code runs only on OS>=5.

************ WARNING :  ARM CODE DOES NOT RUN ON POSE **************************


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. In compile mode,
the EDIT button launch QED doc editor (if present) on the selected file.

 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). When run is
over, any key hit returns to VFSDos or PPShell.

PP supports cooperation with doc editor QED ( http://www.qland.de/qed/ ).
Version >= 2.73 is required. 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 7185:1990 level 0. In particular,it
supports
- nonlocal goto,
- procedure and function as parameter,
- standard syntax for new and dispose for pointer to record with variant.

 The conformant array parameters are NOT supported.

 There is no runtime range control.

See http://www.morecad.com/standardpascal/home.html for a complete description
and  the demo sources for examples.

 In addition, the language supports some of the Turbo Pascal extensions such as
strings, @ operator, bitwize operators, etc.

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
supports compressed doc.

Files other than input and output which 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 string. 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 on the VFSDos console.

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.
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 IEEE 754 compatible;
- Integer are 32 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. Adresses are aligned
  to the even memory location for data greater than one byte.
- Functions pack and unpack are not currently supported.
- Subrange types are packed: a variable declared of type 0..65535 uses 2 bytes
  in memory.
- Function odd and sqr are implemented inline and may not be invoqued as 
  function parameter.
- Boolean expressions are evaluated from left to right and the evaluation is
  aborted as soon as the result is known: in the expression a or b, the 
  expression b is not evaluated if the value of a is true.
- Other expressions and assignement statements are evaluated from right to left.
  In the statement t[i]:=a+b, the expression b is evaluated first, then a and
  then i (it may be important in the case of function with side effect).
- Program paramater may be of type file, text or string.

Additional functions and procedures:
------------------------------------

- gotoxy(x,y), procedure, positions the cursor at the desired  screen position.
- textmode(mode), procedure, selects video mode: 1=32 cols 0=40 cols.
- clrscr, procedure, clears the screen.
- delay(n) waits for n milliseconds.
- random(n) returns a pseudo-random integer in the range 0..n-1.


Non standard features:
----------------------

1. Most constant expression computable at compilation time are allowed anywhere
a constant value is expected.

examples :

const
  n  = 5;
  nn = 2*n;

type
  table = array[0..nn-1] of n..3*n;

Mathematical functions sin, exp, arctan, sqrt, log are not allowed in constant
declaration.

2. The packed array [1..?] of char type not supported for reading and writing.
It is replaced in version >= 1.01a by the usual string type.

-  string[n] denotes a zero terminated string of at most n characters;
-  the default size is 63 characters not including the terminal zero. Therefore,
   string is equivalent to string[63];
-  the first character of a string s is accessed by s[1];
-  The null string '' is allowed, it is equivalent to chr(0);

The following operators are supported for string types:
-  comparison with lexicographic order <, <=, >, >=, =, <>
-  concatenation +

The string type is compatible with the char type and with any other string type,
A string type var parameter is comptatible with any other string type variable.
The inline function "length" returns the actual string length

The string type is allowed as return type of a function.

3. The directive "inline" allows to insert 68000 or THUMB native code such as
   PalmOS API systrap's. When calling an inline procedure or function,
   the specified sequence of 16 bit constant in inserted. The constant in an
   inline sequence may be
    - any 16 bit integer constant;
    - any string constant (completed by zero for word alignement);
    - @VariableIdentifier, to define the 16 bit offset of the variable relative
      to A5 for global variables and to A6 for locals (mode 68k only, not in ARM
      mode).
    - @ProcedureOrFunctionIdentifier to define the offset of the defined
      procedure or function relative to the current program counter pc (mode 68k
      only, not in ARM mode).

4. Character '$' starts hexadecimal representation integers.

5. Underscore '_'is allowed inside identifiers.

6. Hard button page up stops the program while writing on the console.

7. The read procedure applied to a character is bufferised (batch mode). To use
   the interactive mode, use c:=input^; get(input). The variable input must be
   declared in the program parameters : program name(input); ...

8. The C++ style comment is supported : character following // are ignored until
   the end of line.

9. A predefined type "pointer" is assignement compatible with all other pointer
   types. The domain type of the "pointer" type is "pointer".

10.Typeless Var parameter are supported. In this case, any variable is
   compatible in the actual parameter list.

11.Additionnal keywords "shl" and "shr" are the usual shift operators. They have
   the same precedence as *.

12.Additionnal keyword "xor" performs the exclusive or with the same precedence
   as "or"

13.Boolean operators "or", "and" and "xor" perform bitwise operations when they
   apply on integer.

14.Function "sizeof" applied to a variable defines a constant equal to the
   number of byte of the variable.

15.Procedural type are allowed, e.g.
   type ProcType=procedure(var i:integer);

16.Adress operator '@' applied to a variable, a function or a procedure returns
   a pointer type, e.g. p:=@f;

17.Set are allowed in constant declaration. e.g.
   const op = ['+','-','*','/'];

18.In the armlet mode, the directive "systrap" defines a procedure or function
   as a call to a OS function. e.g.
   
   Procedure WinDrawChars(const chrs:string;len:Int16;x,y:Coord); systrap $220;
   
   The systrap number is anded with $00000fff. Only the three last hexadecimal
   digits are taken into account in the systrap number. The compiler
   automatically generates endian swapping call for parameter conversion.

Compilation directives
----------------------

{$i filename} include the file at the position specified

{$r resourcefilename} specifies a resource file to include to the PRC file

{$appl creator} specifies to build a 'appl' type PRC with the specified creator.
The creator must be a sequence of 4 characters in the range '!'..'~' (33..127).
In this case the following standard features are not allowed
  - all file and text type;
  - file and text standard function (get, put, read(ln), write(ln), eof, eoln);
  - mathematical functions (sin, arctan, exp, log, sqrt, cos);
  - additionnal console function (gotoxy, clrscr);

Launch parameters cmd (16 bit integer), cmdPBP (pointer), launchFlags (16 bit 
integer) must be declared in the program header and declared in global variable
section if used. The scope of these variables is the main program section and
they cannot be invoqued in other functions or procedure.
If a program is lauched with a nonzero cmd value, the global variables segment
is not initialised. The non local goto's in destination of the main program
section, constant strings and precomuted sets invoque global memory and must not
be used in a program section executed with nonzero cmd parameter. See demo
ppShell.pas (source code of PPShell rewriten in Pascal) for further details.

{$code xxxx,yyyy,zzzz,nnn} creates a resource of type zzzz identifier and nnn
(a sequence of digits). xxxx is the type and yyyy is the creator of the PRC. The
name is specified in the program header. This directive allows to use PP as a
code resource editor useful for programming hackmaster extensions, multi segment
application and shared libraries (see sample CaseHack.pas, Multi.pas and
GaussLib.pas).
The code segment contains in this order
- the main program section if it is not empty
- the procedures and functions in the order they are declared.
You may declare global variables in a code resource, but the corresponding data
resource is not created. These declarations should only be used in case of
multi-segment application where the same declaration occurs in the main program
file. They are used do define the variable access to the data segment in the
compiled code.
By default, the constant strings and precompiled set are stored in the data
segment. To avoid problems in code ressource, you may use the directive {$c+}
(see further) to force constant storage in the current code segment.

Program parameter must be declared as global variable. The scope of the program
parameters is the main program section. They cannot be invoqued in other
procedure or functions.

{$armlet xxxx,yyyy,zzzz,nnn} creates a resource of type zzzz identifier and nnn
(a sequence of digits). xxxx is the type and yyyy is the creator of the PRC. The
generated code is native ARM and the created resource may be called throught the
pceNativeCall function. The global variable section of an armlet corresponds to
the data passed to pceNativeCall function.
The result is an error code it is nonzero in case of integer division by zero.

{$define xxxx} sets symbol xxx as defined. 16 symbols are allowed with no
interaction with other identifier nor keyword

{$undef xxxx} set symbol xxx as undefined, but do not erase it.

{$ifdef xxxx} {$ifndef xxxx} {$else} {$endif} are usual conditionnal compilation
directives.

{$c+} force constant litteral strings and precomuted sets to be stored in the
code segment. In "code" mode, local constants are automatically stored in the
code. If no global constant occurs, the use of this directive is unnecessary.

{$c-} force constant litteral strings and precomuted sets to be stored in the
data segment.


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.

Acknowledgement:
----------------

Thanks to

- Harry Konstas
- Laurent Duveau
- Peter Obukhov
- John Newell

for their contribution and help in the development of PP.

HISTORY:
--------
2.00   may 2nd. 2003 : Real computation and systrap directive in ARM mode, minor
       fixes.

1.08   apr 8th.  2003 : bug fixes, string type allowed as program parameter, set
       allowed in constant declaration. Sets in ARM mode.

1.07   feb 14th.  2003 : minor changes, bug fixes (with statement, real and
       string comparison, strings in armlets)

1.06   feb  5th.  2003 : large code bug fix, conditionnal directives, {$c+/-}
       directive, change in the {$code ...} directive syntax, inline extensions.

1.05d  jan 17th.  2003 : bug fix in "in" operator.

1.05c  jan. 1st.  2003 : bug fixes : infinite loop when execute readln; StdioLib
       update (accepts bookmark in source doc file); bug in reset(f,'filename');

1.05b  Dec. 25th. 2002 : bug fixes : with statement and pointers, char to string
       conversion.

1.05a  Dec  10th. 2002 : procedural type, address operator.

1.04d  Nov  20th. 2002 : sizeof function and code directive.

1.03g  Nov  15th. 2002 : Bugs fixes.

1.03f  Nov. 11th. 2002 : additionnal support for Palm applications. 32 bit
       integers, pointer type, xor and shift operator, bitwise operations and
       the usual bug fixes.

1.01a: Oct. 1st,2002: Bug Fixes on reals, Constant set precomputation,
       additionnal features (strings, inline functions and procedures, include
       directive).

1.00d: Sept. 13th,2002: Bug Fixes, 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 a Tungsten T using
  OnBoardC, QED and RsrcEdit.

* PP Shell was written by Harry Konstas on a m505 using OnBoardC, QED and
  RsrcEdit, translated into Pascal by Philippe Guillot.



Philippe GUILLOT
ph.guillot@wanadoo.fr

