
Free  Pascal  :

Users'  manual

==============================================================================================================================

                                                     Users' manual for Free Pascal, version 1.0.0

                                                                                                                       1.8

                                                                                                            July 2000


Micha"el Van Canneyt
Florian Kl"ampfl
______________________________________________________________________________________________________________________________



Contents
1   Introduction                                                                                                    4

    1.1    About this document  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     4

    1.2    About the compiler  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 *  4

    1.3    Getting more information.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     5


2   Installing the compiler                                                                                    6

    2.1    Before Installation :  Requirements   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     6

           2.1.1      System requirements  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     6

           2.1.2      Software requirements   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     6

    2.2    Installing the compiler. .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 * 7

           2.2.1      Installing under DOS or Windows   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     7

           2.2.2      Installing under Linux  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .     9

    2.3    Optional configuration steps  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    10

    2.4    Testing the compiler   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 10


3   Compiler usage                                                                                             12

    3.1    File searching  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    12

           3.1.1      Command line files  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *12

           3.1.2      Unit files   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    12

           3.1.3      Include files  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    14

           3.1.4      Object files   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    14

           3.1.5      Configuration file  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   15

           3.1.6      About long filenames .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    15

    3.2    Compiling a program  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    15

    3.3    Compiling a unit   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   16

    3.4    Units, libraries and smartlinking   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    16

    3.5    Creating an executable for GO32V1 and PMODE/DJ targets  .  .  .  .  .  .  .  .  .    16

           3.5.1      GO32V1 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    16

           3.5.2      PMODE/DJ   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *17

    3.6    Reducing the size of your program   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    18


4   Compiling problems                                                                                      19



                                                              1

___________________________________________________________________________________________________________________CONTENTS________*
 *___
    4.1    General problems  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  19

    4.2    Problems you may encounter under DOS    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    19


5   Compiler configuration                                                                                 20

    5.1    Using the command-line options   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    20

           5.1.1      General options  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   20

           5.1.2      Options for getting feedback    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    21

           5.1.3      Options concerning files and directories   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    21

           5.1.4      Options controlling the kind of output. .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    22

           5.1.5      Options concerning the sources (language options)   .  .  .  .  .  .  .  .  .  .  .    24

    5.2    Using the configuration file   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    25

           5.2.1      #IFDEF    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    26

           5.2.2      #IFNDEF    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   26

           5.2.3      #ELSE   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    27

           5.2.4      #ENDIF   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    27

           5.2.5      #DEFINE    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   27

           5.2.6      #UNDEF  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   27

           5.2.7      #WRITE  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   27

           5.2.8      #INCLUDE    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 28

           5.2.9      #SECTION .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 28

    5.3    Variable substitution in paths  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    29


6   Porting Turbo Pascal Code                                                                          30

    6.1    Things that will not work   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    30

    6.2    Things which are extra .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    31

    6.3    Turbo Pascal compatibility mode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    33

    6.4    A note on long file names under dos  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    34


7   Utilities and units that come with Free Pascal                                             35

    7.1    Demo programs and examples  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    35

    7.2    Supplied programs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 35

           7.2.1      ppudump program  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    35

           7.2.2      ppumove program   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    36

           7.2.3      ptop - Pascal source beautifier   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    37

           7.2.4      rstconv program   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 41

           7.2.5      fpcmake  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    41

    7.3    Supplied units .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    41

           7.3.1      Units common to all platforms   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    41

           7.3.2      Under DOS  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   42

           7.3.3      Under Windows    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *42

           7.3.4      Under Linux   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   43
                                                                 2

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           7.3.5      Under OS/2  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    43


8   Debugging your Programs                                                                            44

    8.1    Compiling your program with debugger support .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    44

    8.2    Using gdb to debug your program .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    45

    8.3    Caveats when debugging with gdb   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    46

    8.4    Support for gprof, the gnu profiler    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    47

    8.5    Detecting heap memory leaks  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    47

    8.6    Line numbers in run-time error backtraces  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    48

    8.7    Combining heaptrc and lineinfo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    48


9   CGI programming in Free Pascal                                                                 50

    9.1    Getting your data    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  50

           9.1.1      Data coming through standard input.   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    51

           9.1.2      Data passed through an environment variable  .  .  .  .  .  .  .  .  .  .  .  .  .  .    52

    9.2    Producing output  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  54

    9.3    I'm under Windows, what now ?   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    54


A   Alphabetical listing of command-line options                                               56


B   Alphabetical list of reserved words                                                               59


C   Compiler messages                                                                                        60

    C.1    General compiler messages .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    60

    C.2    Scanner messages.   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 61

    C.3    Parser messages .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   64

    C.4    Type checking errors  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *75

    C.5    Symbol handling   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  77

    C.6    Code generator messages .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    79

    C.7    Errors of assembling/linking stage   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    83

    C.8    Unit loading messages.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    84

    C.9    Command-line handling errors    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    85

    C.10   Assembler reader errors.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    87

           C.10.1     General assembler errors  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    87

           C.10.2     I386 specific errors  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  89

           C.10.3     m68k specific errors.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *91


D   Run time errors                                                                                            92


E   The Floating Point Coprocessor emulator                                                    95


F   A sample gdb.ini file                                                                                      97


                                                                 3


Chapter   1


Introduction
1.1        About  this  document


This is the user's manual for Free Pascal.  It describes the installation and use of the Free
Pascal compiler on the different supported platforms.  It does not attempt to give an exhaus-
tive  list  of  all  supported  commands,  nor  a  definition  of  the  Pascal  language.  Look  at  the
Reference guide for these things.  For a description of the possibilities and the inner workings
of the compiler, see the Programmers' guide.  In the appendices of this document you will
find lists of reserved words and compiler error messages (with descriptions).

This  document  describes  the  compiler  as  it  is/functions  at  the  time  of  writing.  Since  the
compiler is under continuous development,  some of the things described here may be out-
dated.   In  case  of  doubt,  consult  the  README  files,  distributed  with  the  compiler.   The
README files are, in case of conflict with this manual, authoritative.
1.2        About  the  compiler


Free Pascal is a 32-bit compiler for the i386 and m68k processors1 .  Currently, it supports 7
operating systems:


    o  dos

    o  linux

    o  Atari (version 0.99.5 only)

    o  Amiga (version 0.99.5 only)

    o  Windows 32-bit

    o  os/2 (using the EMX package, so it also works on DOS/Windows)

    o  FreeBSD (usable, but still under development).


Free Pascal is designed to be, as much as possible, source compatible with Turbo Pascal 7.0
and Delphi 5 (although this goal is not yet attained), but it also enhances these languages
with  elements  like  function  overloading.  And,  unlike  these  ancestors,  it  supports  multiple
platforms.
___________________________________________________1
     Work is being done on a port to ALPHA Architecture
                                                              4

__________________________________________________________________________1.3.___GETTING_MORE_INFORMATION._________________________*
 *___
It also differs from them in the sense that you cannot use compiled units from one system
for the other.

Also, at the time of writing, there is only a early beta version of an Integrated Development
Environment (IDE) available for Free Pascal.

Free Pascal consists of three parts :


   1.  The compiler program itself.

   2.  The Run-Time Library (RTL).

   3.  Utility programs and units.


Of these you only need the first two, in order to be able to use the compiler.  In this document,
we describe the use of the compiler.  The RTL is described in the Reference guide.
1.3        Getting  more  information.


If the documentation doesn't give an answer to your questions, you can obtain more infor-
mation on the Internet, on the following addresses:


    o  http://www.freepascal.org/ is the main site.  It contains also useful mail addresses and
       links to other places.  It also contains the instructions for inscribing to the mailing-list.

    o  http://www.brain.uni-freiburg.de/"klaus/fpc/fpc.html  is  a  mirror  of  the  main  Free
       Pascal information site.


Both places can be used to download the Free Pascal distribution, although you can probably
find them on other places also.

Finally, if you think something should be added to this manual (entirely possible), please do
not hesitate and contact me at michael@freepascal.org.  .

Let's get on with something useful.
                                                                 5


Chapter   2


Installing   the   compiler
2.1        Before  Installation  :   Requirements



2.1.1       System  requirements

The compiler needs at least the following hardware:


   1.  An I386 or higher processor.  A coprocessor is not required, although it will slow down
       your program's performance if you do floating point calculations.

   2.  4  Mb  of  free  memory.   Under  dos,  if  you  use  DPMI  memory  management,  such  as
       under Windows, you will need at least 16 Mb.

   3.  At least 500 Kb.  free disk space.
2.1.2       Software  requirements

Under DOS


The dos distribution contains all the files you need to run the compiler and compile pascal
programs.



Under Linux


Under linux you need to have the following programs installed :


   1.  gnu as, the gnu assembler.

   2.  gnu ld, the gnu linker.

   3.  Optionally (but highly recommended) :  gnu make.  For easy recompiling of the com-
       piler and Run-Time Library, this is needed.


Other than that, Free Pascal should run on almost any I386 linux system.



Under Windows


The dos distribution contains all the files you need to run the compiler and compile pascal
programs.  However, it may be a good idea to install the mingw32 tools or the cygwin devel-
opment tools.  Links to both of these tools can be found on http://www.freepascal.org



                                                              6

_______________________________________________________________________________2.2.___INSTALLING_THE_COMPILER._____________________*
 *___
Under OS/2


While the Free Pascal distribution comes with all necessary tools, it is a good idea to install
the EMX extender in order to compile and run programs with the Free Pascal compiler.  The
EMX extender can be found on:
http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html
2.2        Installing  the  compiler.


The installation of Free Pascal is easy,  but is platform-dependent.  We discuss the process
for each platform separately.
2.2.1       Installing  under  DOS  or  Windows

Mandatory installation steps.


First, you must get the latest distribution files of Free Pascal.  They come as zip files, which
you  must  unzip  first,  or  you  can  download  the  compiler  as  a  series  of  separate  files.  This
is  especially  useful  if  you  have  a  slow  connection,  but  it  is  also  nice  if  you  want  to  install
only some pats of the compiler distribution.  The distribution zip file contains an installation
program INSTALL.EXE. You must run this program to install the compiler.

The screen of the installation program looks like figure 2.1.

The program allows you to select:


    o  What components you wish to install.  e.g do you want the sources or not, do you want
       docs or not.  Items that you didn't download when downloading as separate files, will
       not be enabled, i.e.  you can't select them.

    o  Where you want to install (the default location is C:\PP).


In order to run Free Pascal from any directory on your system, you must extend your path
variable to contain the C:\PP\BIN directory.  Usually this is done in the AUTOEXEC.BAT
file.  It should look something like this :


   SET  PATH=%PATH%;C:\PP\BIN


(Again, assuming that you installed in the default location).

If  you  want  to  use  the  graphic  drivers  you  must  modify  the  environment  variable  GO32.
Instructions  for  doing  this  can  be  found  in  the  documentation  of  the  Graph  unit,  at  the
InitGraph procedure.



Optional Installation:  The coprocessor emulation


For  people  who  have  an  older  CPU  type,  without  math  coprocessor  (i387)  it  is  necessary
to install a coprocessor emulation, since Free Pascal uses the coprocessor to do all floating
point operations.

The installation of the coprocessor emulation is handled by the installation program (INSTALL.EXE)
under dos and Windows 32-bit.
                                                                 7

_______________________________________________________________________________2.2.___INSTALLING_THE_COMPILER._____________________*
 *___


                                Figure 2.1:  The dos install program screen.


                                                                 8

_______________________________________________________________________________2.2.___INSTALLING_THE_COMPILER._____________________*
 *___
2.2.2       Installing  under  Linux

Mandatory installation steps.


The linux distribution of Free Pascal comes in three forms:


    o  a tar.gz version, also available as seperate files.

    o  a .rpm (Red Hat Package Manager) version, and

    o  a .deb (debian) version.


All of these packages contain a ELF version of the compiler binaries and units.  the older aout
binaries are no longer distributed, although you still can use the comiler on an aout system
if you recompile it.

If you use the .rpm format, installation is limited to


rpm  -i  fpc-pascal-XXX.rpm


(XXX is the version number of the .rpm file)

If you use debian, installation is limited to


dpkg  -i  fpc-XXX.deb


Here again, XXX is the version number of the .deb file.

You need root access to install these packages.  The .tar file allows you to do an installation
if you don't have root permissions.

When downloading the .tar file, or the separate files, installation is more interactive.

In case you downloaded the .tar file, you should first untar the file, in some directory where
you have write permission, using the following command:


tar  -xvf  fpc.tar


We supposed here that you downloaded the file fpc.tar somewhere from the Internet.  (The
real filename will have some version number in it, which we omit here for clarity.)

When the file is untarred, you will be left with more archive files, and an install program:
an installation shell script.

If you downloaded the files as separate files, you should at least download the install.sh script,
and the libraries (in libs.tar.gz).

To install Free Pascal, all that you need to do now is give the following command:


./install.sh


And then you must answer some questions.  They're very simple, they're mainly concerned
with 2 things :


   1.  Places where you can install different things.

   2.  Deciding  if  you  want  to  install  certain  components  (such  as  sources  and  demo  pro-
       grams).


The script will automatically detect which components are present and can be installed.  It
will only offer to install what has been found.  because of this feature,  you must keep the
original names when downloading, since the script expects this.



                                                                 9

_____________________________________________________________________2.3.___OPTIONAL_CONFIGURATION_STEPS___________________________*
 *___
If you run the installation script as the root user, you can just accept all installation defaults.
If you don't run as root, you must take care to supply the installation program with directory
names  where  you  have  write  permission,  as  it  will  attempt  to  create  the  directories  you
specify.  In principle, you can install it wherever you want, though.

At the end of installation, the installation program will generate a configuration file for the
Free Pascal compiler which reflects the settings that you chose.  It will install this file in the
/etc directory, (if you are not installing as root, this will fail), and in the directory where
you installed the libraries.

If you want the Free Pascal compiler to use this configuration file, it must be present in /etc,
or  you  can  set  the  environment  variable  PPC_CONFIG_PATH.  Under  csh,  you  can  do  this  by
adding a


setenv  PPC_CONFIG_PATH  /usr/lib/ppc/0.99.14


line to your .login file in your home directory.  (see also the next section)
2.3        Optional  configuration  steps


On any platform, after installing the compiler you may wish to set some environment vari-
ables.  The Free Pascal compiler recognizes the following variables :


    o  PPC_EXEC_PATH contains the directory where 'as' and 'ld' are.  (default /usr/bin)

    o  PPC_GCCLIB_PATH  contains  the  directory  where  libgcc.a  is  (no  default).   This  if  for
       linux only.

    o  PPC_CONFIG_PATH specifies an alternate path to find ppc386.cfg (default under linux
       is /etc)

    o  PPC_ERROR_FILE  specifies  the  path  and  name  of  the  error-definition  file.   (default
       /usr/lib/fpc/errorE.msg)


These locations are, however, set in the sample configuration file which is built at the end
of the installation process, except for the PPC_CONFIG_PATH variable, which you must set if
you didn't install things in the default places.



finally


Also  distributed  in  Free  Pascal  is  a  README  file.  It  contains  the  latest  instructions  for
installing Free Pascal, and should always be read first.
2.4        Testing  the  compiler


After the installation is completed and the environment variables are set as described above,
your first program can be compiled.

Included  in  the  Free  Pascal  distribution  are  some  demonstration  programs,  showing  what
the compiler can do.  You can test if the compiler functions correctly by trying to compile
these programs.

The compiler is called


    o  ppc386 under linux



                                                                 10

_____________________________________________________________________________________2.4.___TESTING_THE_COMPILER___________________*
 *___
    o  PPC386.EXE under other target systems.


To compile a program (e.g demo\hello.pp) simply type :


   ppc386  hello


at the command prompt.  If you don't have a configuration file, then you may need to tell
the compiler where it can find the units, for instance as follows:


ppc386  -Fuc:\pp\units\go32v2\rtl  hello


under dos, and under linux you could type


ppc386  -Fu/usr/lib/fpc/0.99.14/units/linux/rtl  hello


This is, of course, assuming that you installed under C:\PP or /usr/lib/fpc/0.99.14, respec-
tively.

If  you  got  no  error  messages,  the  compiler  has  generated  an  executable  called  hello  (no
extension) under linux, and a file hello.exe under dos.

To execute the program, simply type :


   hello


If all went well, you should see the following friendly greeting:


Hello  world


                                                                 11


               Chapter   3


               Compiler   usage



               Here we describe the essentials to compile a program and a unit.  We also describe how to
               make a stand-alone executable of the compiled program under dos.  For more advanced uses
               of the compiler, see the section on configuring the compiler, and the Programmers' guide.

               The examples in this section suppose that you have a ppc386.cfg which is set up correctly,
               and  which  contains  at  least  the  path  setting  for  the  RTL  units.   In  principle  this  file  is
               generated by the installation program.  You may have to check that it is in the correct place
               (see section 5.2 for more information on this).
               3.1        File  searching


               Before  you  start  compiling  a  program  or  a  series  of  units,  it  is  important  to  know  where
               the compiler looks for its source files and other files.  In this section we discuss this, and we
               indicate how to influence this.

Remark:        The use of slashes (/) and backslashes (\) as directory separators is irrelevant, the compiler
               will convert to whatever character is used on the current operating system.  Examples will
               be given using slashes, since this avoids problems on linux.
               3.1.1       Command  line  files

               The file that you specify on the command line, such as in


               ppc386  foo.pp


               will be looked for ONLY in the current directory.  If you specify a directory in the filename,
               then the compiler will look in that directory:


               ppc386  subdir/foo.pp


               will look for foo.pp in the subdirectory subdir of the current directory.

               Under  linux,  the  name  of  this  file  is  case  sensitive,  under  other  operating  systems  (dos,
               Windows NT, os/2) this is not the case.
               3.1.2       Unit  files

               When  you  compile  a  unit  or  program  that  needs  other  units,  the  compiler  will  look  for
               compiled versions of these units in the following way:



                                                                            12

__________________________________________________________________________________________________3.1.___FILE_SEARCHING____________*
 *___
   1.  It will look in the current directory.

   2.  It will look in the directory where the compiler binary is.  (not under linux)

   3.  It will look in all the directories specified in the unit search path.


You  can  add  a  directory  to  the  unit  search  path  with  the  -Fu  option  (See  5.1.3).   Every
occurrence of one of this options will insert a directory to the unit search path.  i.e.  last path
on the command line will be searched first.

The compiler adds several paths to the unit search path:


   1.  The contents of the environment variable XXUNITS, where XX musrt be replaced with
       one of the supported targets:  GO32V2, LINUX,WIN32, OS2.

   2.  The standard unit directory.  This directory is determined from the FPCDIR environment
       variable.  If this variable is not set, then it is defaulted to the following:

           o  On linux:

                  /usr/local/lib/fpc/VERSION
              or
                  /usr/lib/fpc/VERSION

              whichever is found first.

           o  On other OSes:  the compiler binary directory, with '../' appended to it, if it exists.

       After this directory is determined , the following paths are added to the search path:

         (a)  FPCDIR/units/TARGET

         (b)  FPCDIR/units/TARGET/rtl

       Here target must be replaced by the name of the target you are compiling for.


You can see what paths the compiler will search by giving the compiler the -vu option.

On  linux,  the  compiler  will  first  convert  the  filename  of  a  unit  to  all-lowercase.   This  is
necessary, since Pascal is case-independent, and the statements Uses  Unit1; or uses  unit1;
should have the same effect.  Also, unit names that are longer than 8 characters will first be
looked for with their full length.  If the unit is not found with this name, the name will be
truncated to 8 characters, and the compiler will look again in the same directories, but with
the truncated name.

For instance, suppose that the file foo.pp needs the unit bar.  Then the command


ppc386  -Fu..  -Fuunits  foo.pp


will tell the compiler to look for the unit bar in the following places:


   1.  In the current directory.

   2.  In the directory where the compile binary is (not under linux).

   3.  In the parent directory of the current directory.

   4.  In the subdirectory units of the current directory

   5.  In the standard unit directory.


                                                                 13

__________________________________________________________________________________________________3.1.___FILE_SEARCHING____________*
 *___
If the compiler finds the unit it needs, it will look for the source file of this unit in the same
directory where it found the unit.  If it finds the source of the unit, then it will compare the
file times.  If the source file was modified more recent than the unit file,  the compiler will
attempt to recompile the unit with this source file.

If the compiler doesn't find a compiled version of the unit, or when the -B option is specified,
then  the  compiler  will  look  in  the  same  manner  for  the  unit  source  file,  and  attempt  to
recompile it.

It  is  recommended  to  set  the  unit  search  path  in  the  configuration  file  ppc386.cfg.  If  you
do this, you don't need to specify the unit search path on the command-line every time you
want to compile something.
3.1.3       Include  files

If you include files in your source with the {$I  filename} directive, the compiler will look
for it in the following places:


   1.  It will look in the path specified in the incude file name.

   2.  It will look in the directory where the current source file is.

   3.  it will look in all directories specified in the include file search path.


You can add files to the include file search path with the -I (See 5.1.3) option.

As an example, consider the following include statement in a file units/foo.pp:
{$i  ../bar.inc}
Then the following command :


ppc386  -Iincfiles  units/foo.pp


will cause the compiler to look in the following directories for bar.inc:


   1.  the parent directory of the current directory

   2.  the units subdirectory of the current directory

   3.  the incfiles directory of the current directory.
3.1.4       Object  files

When you link to object files (using the {$L  file.o} directive,  the compiler will look for
this file in the same way as it looks for include files:


   1.  It will look in the path specified in the object file name.

   2.  It will look in the directory where the current source file is.

   3.  it will look in all directories specified in the object file search path.


You can add files to the object file search path with the -Fo (See 5.1.3) option.



                                                                 14

______________________________________________________________________________________3.2.___COMPILING_A_PROGRAM___________________*
 *___
3.1.5       Configuration  file

Unless you specify the -n (See 5.1.1) option, the compiler will look for a configuration file
ppc386.cfg in the following places:


    o  Under linux

          1.  The current directory.

          2.  In your home directory, it looks for .ppc386.cfg.

          3.  The directory specified in the environment variable PPC_CONFIG_PATH, and if it's
              not set under /etc.

    o  Under all other OSes:

          1.  The current directory.

          2.  If it is set, the directory specified in the environment variable.  PPC_CONFIG_PATH.

          3.  The directory where the compiler is.
3.1.6       About  long  filenames

Free Pascal can handle long filenames under Windows 32-bit; it will use support for long
filenames if it is available.

If no support for long filenames is present, it will truncate unit names to 8 characters.

It is not recommended to put units in directories that contain spaces in their names, since
the linker doesn't understand such filenames.
3.2        Compiling  a  program


Compiling a program is very simple.  Assuming that you have a program source in the file
prog.pp, you can compile this with the following command:


   ppc386  [options]  prog.pp


The square brackets [  ] indicate that what is between them is optional.

If your program file has the .pp or .pas extension, you can omit this on the command line,
e.g.  in the previous example you could have typed:


   ppc386  [options]  prog


If all went well, the compiler will produce an executable, or, for version 1 of the dos extender,
a file which can be converted to an executable.

Unless  you  are  using  dos  and  version  1  of  the  dos  extender,  the  file  you  obtained  is  the
executable.  You  can  execute  it  straight  away,  you  don't  need  to  do  anything  else.  Under
version 1 of the dos extender, additional processing is required.  See section 3.5 on how to
create an executable in this case.

You  will  notice  that  there  is  also  another  file  in  your  directory,  with  extensions  .o.   This
contains  the  object  file  for  your  program.  If  you  compiled  a  program,  you  can  delete  the
object file (.o), but not if you compiled a unit.  Then the object file contains the code of the
unit, and will be linked in any program that uses the unit you compiled, so you shouldn't
remove it.
                                                                 15

               ______________________________________________________________________________________________3.3.___COMPILING_A_UNI*
 *T_________________
               3.3        Compiling  a  unit


               Compiling  a  unit  is  not  essentially  different  from  compiling  a  program.   The  difference  is
               mainly that the linker isn't called in this case.

               To compile a unit in the file foo.pp, just type :


                  ppc386    foo


               Recall the remark about file extensions in the previous section.

               When all went well, you will be left with 2 (two) unit files:


                  1.  foo.ppu This is the file describing the unit you just compiled.

                  2.  foo.o This file contains the actual code of the unit.  This file will eventually end up in
                      the executables.


               Both files are needed if you plan to use the unit for some programs.  So don't delete them.
               If you want to distribute the unit, you must provide both the .ppu and .o file.  One is useless
               without the other.

Remark:         Under  linux,  a  unit  source  file  must  have  a  lowercase  filename.  Since  Pascal  is  case  in-
               dependent,  you can specify the names of units in the uses clause in either case.  To get a
               unique filename, the Free Pascal compiler changes the name of the unit to all lowercase when
               looking for unit files.

               The compiler produces lowercase files, so your unit will be found, even if your source file has
               uppercase letters in it.  Only when the compiler tries to recompile the unit, it will not find
               your source because of the uppercase letters.
               3.4        Units,  libraries  and  smartlinking


               The Free Pascal compiler supports smartlinking and the creation of libraries.  However, the
               default  behaviour  is  to  compile  each  unit  into  1  big  object  file,  which  will  be  linked  as  a
               whole into your program.

               Not only is it possible to compile a shared library under Windows 32-bit and linux, but
               also it is possible to take existing units and put them together in 1 static or shared library
               (using the ppumove tool)
               3.5        Creating an executable for GO32V1 and PMODE/DJ

                          targets


               The GO32V1 platform is officially no longer supported, so this section is of interest only to
               people who wish to make go32V1 binaries anyway.
               3.5.1       GO32V1

               When  compiling  under  dos,  GO32V2  is  the  default  target.   However,  if  you  use  go32V1
               (using the -TGO32V1 switch), the compilation process leaves you with a file which you cannot
               execute right away.  There are 2 things you can do when compiling has finished.

               The first thing is to use the dos extender from D.J. Delorie to execute your program :
                                                                                16

________________3.5.___CREATING_AN_EXECUTABLE_FOR_GO32V1_AND_PMODE/DJ_TARGETS______________________________________________________*
 *___
   go32  prog


This is fine for testing, but if you want to use a program regularly, it would be easier if you
could just type the program name, i.e.


   prog


This can be accomplished by making a dos executable of your compiled program.

There two ways to create a dos executable (under dos only):


   1.  if the GO32.EXE is already installed on the computers where the program should run,
       you must only copy a program called STUB.EXE at the begin of the AOUT file.  This
       is accomplished with the AOUT2EXE.EXE program.  which comes with the compiler:


       AOUT2EXE  PROG


       and you get a dos executable which loads the GO32.EXE automatically.  the GO32.EXE
       executable must be in current directory or be in a directory in the PATH variable.

   2.  The  second  way  to  create  a  dos  executable  is  to  put  GO32.EXE  at  the  beginning  of
       the AOUT file.  To do this, at the command prompt, type :


       COPY  /B  GO32.EXE+PROG  PROG.EXE


       (assuming  Free  Pascal  created  a  file  called  PROG,  of  course.)   This  becomes  then  a
       stand-alone  executable  for  dos,  which  doesn't  need  the  GO32.EXE  on  the  machine
       where it should run.
3.5.2       PMODE/DJ

You can also use the PMODE/DJ extender to run your Free Pascal applications.  To make
an executable which works with the PMODE extender, you can simply create an GO32V2
executable (the default), and then convert it to a PMODE executable with the following two
extra commands:


   1.  First, strip the GO32V2 header of the executable:


       EXE2COFF  PROG.EXE


       (we suppose that PROG.EXE is the program generated by the compilation process.

   2.  Secondly, add the PMODE stub:


       COPY  /B  PMODSTUB.EXE+PROG  PROG.EXE


       If the PMODSTUB.EXE file isn't in your local directory, you need to supply the whole
       path to it.


That's it.  No additional steps are needed to create a PMODE extender executable.

Be aware, though, that the PMODE extender doesn't support virtual memory, so if you're
short  on  memory,  you  may  run  unto  trouble.  Also,  officially  there  is  not  support  for  the
PMODE/DJ  extender.   It  just  happens  that  the  compiler  and  some  of  the  programs  it
generates, run under this extender too.
                                                                 17

               __________________________________________________________3.6.___REDUCING_THE_SIZE_OF_YOUR_PROGRAM__________________*
 *__________________
               3.6        Reducing  the  size  of  your  program


               When you created your program, it is possible to reduce its size.  This is possible, because the
               compiler leaves a lot of information in the program which, strictly speaking, isn't required
               for  the  execution  of  it.  The  surplus  of  information  can  be  removed  with  a  small  program
               called strip.  It comes with the GO32 development environment under dos, and is standard
               on linux machines where you can do development.  The usage is simple.  Just type


               strip  prog


               On the command line, and the strip program will remove all unnecessary information from
               your program.  This can lead to size reductions of up to 30 %.

Remark:         In the Win32 version, strip is called stripw.

               You can use the -Xs switch to let the compiler do this stripping automatically at program
               compile time (the switch has no effect when compiling units).

               Another technique to reduce the size of a program is to use smartlinking.  Normally, units
               (including the system unit) are linked in as a whole.  It is however possible to compile units
               such that the can be smartlinked.  This means that only the functions and procedures are
               linked  in  your  program,  leaving  out  any  unnecessary  code.  This  technique  is  described  in
               full in the programmers guide.
                                                                                18


Chapter   4


Compiling   problems
4.1        General  problems


    o  IO-error  -2  at  ...  :  Under linux you can get this message at compiler startup.  It
       means typically that the compiler doesn't find the error definitions file.  You can correct
       this mistake with the -Fr option under linux.  (See 5.1.3)

    o  Error :  File not found :  xxx or Error:  couldn't compile unit xxx: This typically
       happens when your unit path isn't set correctly.  Remember that the compiler looks
       for units only in the current directory, and in the directory where the compiler itself
       is.  If you want it to look somewhere else too, you must explicitly tell it to do so using
       the -Fu option (See 5.1.3).  Or you must set op a configuration file.
4.2        Problems  you  may  encounter  under  DOS


    o  No space in environment.
       An error message like this can occur, if you call SET_PP.BAT in the AUTOEXEC.BAT.
       To solve this problem, you must extend your environment memory.  To do this, search
       a line in the CONFIG.SYS like


       SHELL=C:\DOS\COMMAND.COM


       and change it to the following:


       SHELL=C:\DOS\COMMAND.COM  /E:1024


       You may just need to specify a higher value, if this parameter is already set.

    o    Coprocessor missing
       If the compiler writes a message that there is no coprocessor,  install the coprocessor
       emulation.

    o  Not enough DPMI memory
       If you want to use the compiler with DPMI you must have at least 7-8 MB free DPMI
       memory, but 16 Mb is a more realistic amount.

                                                             19


Chapter   5


Compiler   configuration



The output of the compiler can be controlled in many ways.  This can be done essentially in
two distinct ways:


    o  Using command-line options.

    o  Using the configuration file:  ppc386.cfg.


The  compiler  first  reads  the  configuration  file.   Only  then  the  command  line  options  are
checked.  This creates the possibility to set some basic options in the configuration file, and
at the same time you can still set some specific options when compiling some unit or program.
First we list the command line options, and then we explain how to specify the command
line options in the configuration file.  When reading this, keep in mind that the options are
case sensitive.  While this is customary for linux, it isn't under dos.
5.1        Using  the  command-line  options


The available options for version 0.99.10 of the compiler are listed by category (see appendix
A for a listing as generated by the compiler):
5.1.1       General  options

-h  if you specify this option, the compiler outputs a list of all options, and exits after that.

-?  idem as -h, waiting after every screenfull for the enter key.

-i This  option  tells  the  compiler  to  print  the  copyright  information.   You  can  give  it  an
       option, as -ixxx where xxx can be one of the following:

       D    :  Returns the compiler date.

       V    :  Returns the compiler version.

       SO     :  Returns the compiler OS.

       SP    :  Returns the compiler processor.

       TO     :  Returns the target OS.

       TP     :  Returns the target Processor.

-l This option tells the compiler to print the Free Pascal logo on standard output.  It also
       gives you the Free Pascal version number.



                                                             20

_________________________________________________________________5.1.___USING_THE_COMMAND-LINE_OPTIONS_____________________________*
 *___
-n  Tells the compiler not to read default the configuration file.  You can still pass a config-
       uration file with the @ option.
5.1.2       Options  for  getting  feedback

-vxxx     Be verbose.  xxx is a combination of the following :

           o  e :  Tells the compiler to show only errors.  This option is on by default.

           o  i :  Tells the compiler to show some general information.

           o  w :  Tells the compiler to issue warnings.

           o  n :  Tells the compiler to issue notes.

           o  h :  Tells the compiler to issue hints.

           o  l :  Tells the compiler to show the line numbers as it processes a file.  Numbers
              are shown per 100.

           o  u :  Tells the compiler to print information on the units it loads.

           o  t :  Tells the compiler to print the names of the files it tries to open.

           o  p  :  Tells  the  compiler  to  print  the  names  of  procedures  and  functions  as  it  is
              processing them.

           o  c :  Tells the compiler to warn you when it processes a conditional.

           o  m :  Tells the compiler to write which macros are defined.

           o  d :  Tells the compiler to write other debugging info.

           o  a :  Tells the compiler to write all possible info.  (this is the same as specifying all
              options)

           o  0  :  Tells  the  compiler  to  write  no  messages.   This  is  useful  when  you  want  to
              override the default setting in the configuration file.

           o  b :  Tells the compiler to show all procedure declarations if an overloaded function
              error occurs.

           o  x :  Tells the compiler to output some executable info (for Win32 platform only).

           o  r  :  Rhide/GCC  compatibility  mode:  formats  the  errors  differently,  so  they  are
              understood by RHIDE.
5.1.3       Options  concerning  files  and  directories

-exxx     xxx specifies the directory where the compiler can find the executables as (the assem-
       bler) and ld (the linker).

-FD    same as -e.

-Fexxx      This option tells the compiler to write errors, etc.  to the file named xxx.

-FExxx       tells the compiler to write the executable and units in directory xxx instead of th
       current directory.

-FIxxx      Adds xxx to the include file search path.

-Flxxx     Adds xxx to the library searching path, and is passed to the linker.

-FLxxx      (linux only) Tells the compiler to use xxx as the dynamic linker.  Default this is
       /lib/ld-linux.so.2, or /Hlib/ld-linux.so.1, depending on which one is found first.

                                                                 21

_________________________________________________________________5.1.___USING_THE_COMMAND-LINE_OPTIONS_____________________________*
 *___
-Foxxx      Adds  xxx  to  the  object  file  search  path.  This  path  is  used  when  looking  for  files
       that need to be linked in.

-Frxxx     xxx specifies the file which contain the compiler messages.  Default the compiler has
       built-in messages.  Specifying this option will override the default messages.

-Fuxxx      Add xxx to the unit search path.  Units are first searched in the current directory.  If
       they are not found there then the compiler searches them in the unit path.  You must
       always supply the path to the system unit.

-FUxxx       Tells the compiler to write units in directory xxx instead of the current directory.
       It overrides the -FE option.

-Ixxx    Add xxx to the include file search path.  This option has the same effect as -Fi.

-P   uses pipes instead of files when assembling.  This may speed up the compiler on os/2
       and linux.  Only with assemblers (such as gnu as) that support piping...
5.1.4       Options  controlling  the  kind  of  output.

for more information on these options, see also Programmers' guide


-a  Tells  the  compiler  not  to  delete  the  assembler  files  it  generates  (not  when  using  the
       internal assembler).  This also counts for the (possibly) generated batch script.

-al  Tells the compiler to include the sourcecode lines in the assembler file as comments.

-ar   tells the compiler to list register allocation and release info in the assembler file.  This is
       primarily intended for debugging the code generated bythe compiler.

-at  tells the compiler to list information about temporary allocations and deallocations in
       the assembler file.

-Axxx      specifies what kind of assembler should be generated .  Here xxx is one of the following
       :

       as   assemble using gnu as.

       asaout      assemble using gnu as for aout (Go32v1).

       nasmcoff        coff (Go32v2) file using Nasm.

       nasmelf       elf32 (Linux) file using Nasm.

       nasmobj        object file using Nasm.

       masm       object file using Masm (Microsoft).

       tasm      object file using Tasm (Borland).

       coff   coff object file (Go32v2) using the internal binary object writer.

       pecoff     pecoff object file (Win32) using the internal binary object writer.

-B   tells the compiler to re-compile all used units, even if the unit sources didn't change since
       the last compilation.

-b  tells  the  compiler  to  generate  browser  info.  This  information  can  be  used  by  an  Inte-
       grated  Development  Environment  (IDE)  to  provide  information  on  classes,  objects,
       procedures, types and variables in a unit.

-bl  is the same as -b but also generates information about local variables, types and proce-
       dures.



                                                                 22

_________________________________________________________________5.1.___USING_THE_COMMAND-LINE_OPTIONS_____________________________*
 *___
-CD     Create a dynamic library.  This is used to transform units into dynamically linkable
       libraries on linux.

-Chxxx       Reserves xxx bytes heap.  xxx should be between 1024 and 67107840.

-Ci   Generate Input/Output checking code.  In case some input/output code of your program
       returns  an  error  status,  the  program  will  exit  with  a  run-time  error.  Which  error  is
       generated depends on the I/O error.

-Cn    Omit the linking stage.

-Co    Generate Integer overflow checking code.  In case of integer errors, a run-time error will
       be generated by your program.

-Cr   Generate Range checking code.  In case your program acesses an array element with an
       invalid index, or if it increases an enumerated type beyond it's scope, a run-time error
       will be generated.

-Csxxx      Set stack size to xxx.

-Ct   generate stack checking code.  In case your program performs a faulty stack operation,
       a run-rime error will be generated.

-CX     Create a smartlinked unit when writing a unit.  smartlinking will only link in the code
       parts that are actually needed by the program.  All unused code is left out.  This can
       lead to substantially smaller binaries.

-dxxx     Define the symbol name xxx.  This can be used to conditionally compile parts of your
       code.

 -E Same as -Cn.

-g  Generate debugging information for debugging with gdb

-gg   idem as -g.

-gd   generate debugging info for dbx.

-gh   use the heaptrc unit (see Unit reference).

-gc   generate checks for pointers.

-Oxxx      optimize the compiler's output; xxx can have one of the following values :

       g   optimize for size, try to generate smaller code.

       G    optimize for time, try to generate faster code (default).

       r  keep certain variables in registers (experimental, use with caution).

       u   Uncertain optimizations

       1   Level 1 optimizations (quick optimizations).

       2   Level 2 optimizations (-O1 plus some slower optimizations).

       3   Level 3 optimizations (-O2 plus -Ou).

       Pn    (Intel only) Specify processor:  n can be one of

              1   optimize for 386/486

              2   optimize for Pentium/PentiumMMX (tm)

              3   optimizations for PentiumPro/PII/Cyrix 6x86/K6 (tm)

       The exact effect of these effects can be found in the Programmers' guide.



                                                                 23

_________________________________________________________________5.1.___USING_THE_COMMAND-LINE_OPTIONS_____________________________*
 *___
-oxxx     Tells the compiler to use xxx as the name of the output file (executable).  Only with
       programs.

-pg   Generate profiler code for gprof.

-s  Tells  the  compiler  not  to  call  the  assembler  and  linker.  Instead,  the  compiler  writes  a
       script, PPAS.BAT under dos, or ppas.sh under linux, which can then be executed to
       produce an executable.  This can be used to speed up the compiling process or to debug
       the compiler's output.

-Txxx      Specifies the target operating system.  xxx can be one of the following:

           o  GO32V1 :  dos and version 1 of the DJ DELORIE extender (no longer main-
              tained).

           o  GO32V2 :  dos and version 2 of the DJ DELORIE extender.

           o  LINUX : linux.

           o  OS2 :  OS/2 (2.x) using the EMX extender.

           o  WIN32 :  Windows 32-bit 32 bit.

-uxxx     undefine the symbol xxx.  This is the opposite of the -d option.

-uxxx     Undefine symbol xxx.

-Xx    executable options.  This tells the compiler what kind of executable should be generated.
       the parameter x can be one of the following:

           o  c :  (linux only) Link with the C library.  You should only use this when you start
              to port Free Pascal to another operating system.

           o  D : Link with dynamic libraries (defines the FPC_LINK_DYNAMIC symbol)

           o  s :  Strip the symbols from the executable.

           o  S : Link with static units (defines the FPC_LINK_STATIC symbol)

           o  X : Link with smartlinked units (defines the FPC_LINK_SMART symbol)
5.1.5       Options  concerning  the  sources  (language  options)

for more information on these options, see also Programmers' guide


-Rxxx      Specifies what kind of assembler you use in your asm assembler code blocks.  Here
       xxx is one of the following:

       att     asm blocks contain AT&T-style assembler.  This is the default style.

       intel    asm blocks contain Intel-style assembler.

       direct     asm blocks should be copied as-is in the assembler, only replacing certain vari-
              ables.  file.

-S2   Switch  on  Delphi  2  extensions.   This  is  different  from  -Sd  because  some  Free  Pascal
       constructs are still available to you.

-Sc   Support C-style operators, i.e.  *=,  +=,  /=  and  -=.

-Sd   Tells the compiler to be Delphi compatible.  This is more strict than the -S2 option,
       since some fpc extensions are switched off.



                                                                 24

_______________________________________________________________________5.2.___USING_THE_CONFIGURATION_FILE_________________________*
 *___
-SeN     The  compiler  stops  after  the  N-th  error.   Normally,  the  compiler  tries  to  continue
       compiling after an error,  until 50 errors are reached,  or a fatal error is reached,  and
       then  it  stops.  With  this  switch,  the  compiler  will  stop  after  the  N-th  error  (if  N  is
       omitted, a default of 1 is assumed).

-Sg   Support the label and goto commands.  By default these are not supported.  You must
       also specify this option if you use labels in assembler statements.  (if you use the AT&T
       style assember)

-Sh   Use  ansistrings  by  default  for  strings.   If  this  keyword  is  specified,  the  compiler  will
       interpret the string keyword as a ansistring.  Otherwise it is supposed to be a short
       strings (TP style).

-Si  Support C++ style INLINE.

-Sm    Support C-style macros.

-So   Try to be Borland TP 7.0 compatible (no function overloading etc.).

-Sp   Try to be gpc (gnu pascal compiler) compatible.

-Ss   The name of constructors must be init, and the name of destructors should be done.

-St   Allow the static keyword in objects.

-Un    Do  not  check  the  unit  name.  Normally,  the  unit  name  is  the  same  as  the  filename.
       This option allows both to be different.

-Us    Compile a system unit.  This option causes the compiler to define only some very basic
       types.
5.2        Using  the  configuration  file


Using the configuration file ppc386.cfg is an alternative to command line options.  When a
configuration file is found, it is read, and the lines in it are treated like you typed them on
the command line.  They are treated before the options that you type on the command line.

You can specify comments in the configuration file with the # sign.  Everything from the #
on will be ignored.

The algorithm to determine which file is used as a configuration file is decribed in 3.1.5 on
page 15.

When  the  compiler  has  finished  reading  the  configuration  file,  it  continues  to  treat  the
command line options.

One of the command-line options allows you to specify a second configuration file:  Specifying
@foo on the command line will open file foo, and read further options from there.  When the
compiler has finished reading this file, it continues to process the command line.

The configuration file allows some kind of preprocessing.  It understands the following direc-
tives, which you should place on the first column of a line :


#IFDEF

#IFNDEF

#ELSE

#ENDIF



                                                                 25

_______________________________________________________________________5.2.___USING_THE_CONFIGURATION_FILE_________________________*
 *___
#DEFINE

#UNDEF

#WRITE

#INCLUDE

#SECTION


They work the same way as their {$...} counterparts in Pascal.

What follows is a description of the different directives.
5.2.1       #IFDEF

Syntax:


#IFDEF  name


Lines following #IFDEF are skipped read if the keyword name following it is not defined.

They  are  read  until  the  keywords  #ELSE  or  #ENDIF  are  encountered,  after  which  normal
processing is resumed.

Example :


#IFDEF  VER0_99_5
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ENDIF


In the above example, /usr/lib/fpc/0.99.5/linuxunits will be added to the path if you're com-
piling with version 0.99.5 of the compiler.
5.2.2       #IFNDEF

Syntax:


#IFNDEF  name


Lines following #IFDEF are skipped read if the keyword name following it is defined.

They  are  read  until  the  keywords  #ELSE  or  #ENDIF  are  encountered,  after  which  normal
processing is resumed.

Example :


#IFNDEF  VER0_99_5
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ENDIF


In the above example, /usr/lib/fpc/0.99.6/linuxunits will be added to the path if you're NOT
compiling with version 0.99.5 of the compiler.



                                                                 26

_______________________________________________________________________5.2.___USING_THE_CONFIGURATION_FILE_________________________*
 *___
5.2.3       #ELSE

Syntax:


#ELSE


#ELSE can be specified after a #IFDEF or #IFNDEF directive as an alternative.  Lines following
#ELSE are skipped read if the preceding #IFDEF #IFNDEF was accepted.

They are skipped until the keyword #ENDIF is encountered, after which normal processing is
resumed.

Example :


#IFDEF  VER0_99_5
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ELSE
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ENDIF


In the above example, /usr/lib/fpc/0.99.5/linuxunits will be added to the path if you're com-
piling  with  version  0.99.5  of  the  compiler,  otherwise  /usr/lib/fpc/0.99.6/linuxunits  will  be
added to the path.
5.2.4       #ENDIF

Syntax:


#ENDIF


#ENDIF  marks  the  end  of  a  block  that  started  with  #IF(N)DEF,  possibly  with  an  #ELSE
between it.
5.2.5       #DEFINE

Syntax:


#DEFINE  name


#DEFINE defines a new keyword.  This has the same effect as a -dname command-line option.
5.2.6       #UNDEF

Syntax:


#UNDEF  name


#UNDEF un-defines a keyword if it existed.  This has the same effect as a -uname command-line
option.
5.2.7       #WRITE

Syntax:
                                                                 27

_______________________________________________________________________5.2.___USING_THE_CONFIGURATION_FILE_________________________*
 *___
#WRITE  Message  Text


#WRITE writes Message  Text to the screen.  This can be useful to display warnings if certain
options are set.

Example:


#IFDEF  DEBUG
#WRITE  Setting  debugging  ON...
-g
#ENDIF


if  DEBUG is defined, this will produce a line


Setting  debugging  ON...


and will then switch on debugging information in the compiler.
5.2.8       #INCLUDE

Syntax:


#INCLUDE  filename


#INCLUDE instructs the compiler to read the contents of filename before continuing to process
options in the current file.

This can be useful if you want to have a particular configuration file for a project (or, under
linux, in your home directory), but still want to have the global options that are set in a
global configuration file.

Example:


#IFDEF  LINUX
   #INCLUDE  /etc/ppc386.cfg
#ELSE
   #IFDEF  GO32V2
      #INCLUDE  c:\pp\bin\ppc386.cfg
   #ENDIF
#ENDIF


This will include /etc/ppc386.cfg if you're on a linux machine, and will include c:\pp\bin\ppc386.cfg
on a dos machine.
5.2.9       #SECTION

Syntax:


#SECTION  name


The #SECTION directive acts as a #IFDEF directive, only it doesn't require an #ENDIF directive.
the special name COMMON always exists, i.e.  lines following #SECTION  COMMON are always read.
                                                                 28

____________________________________________________________________5.3.___VARIABLE_SUBSTITUTION_IN_PATHS__________________________*
 *___
5.3        Variable  substitution  in  paths


To avoid having to edit your configuration files too often, the compiler allows you to specify
the following variables in the paths that you feed to the compiler:


FPCVER          is replaced by the compiler's full version string.

FPCDATE           is replaced by the compiler's date.

FPCTARGET               is replaced by the compiler's target CPU (deprecated).

FPCCPU          is also replaced by the compiler's target CPU.

TARGET          is replaced by the compiler's target OS.(deprecated)

FPCOS        is replaced by the compiler's target OS.


To have these variables subsituted, just insert them with a $ prepended, as follows:


-Fu/usr/lib/fpc/$FPCVER/rtl/$FPCOS


This is equivalent to


-Fu/usr/lib/fpc/0.99.12a/rtl/linux


If the compiler version is 0.99.12a and the target os is linux.

These replacemens are valid on the command-line and also in the configuration file.

On the linux command-line,  you must be careful to escape the $ since otherwise the shell
will expand the variable for you, which may have undesired effects.
                                                                 29


Chapter   6


Porting   Turbo   Pascal   Code



Free  Pascal  was  designed  to  resemble  Turbo  Pascal  as  closely  as  possible.   There  are,  of
course, restrictions.  Some of these are due to the fact that Free Pascal is a 32-bit compiler.
Other restrictions result from the fact that Free Pascal works on more than one operating
system.

In general we can say that if you keep your program code close to ANSI Pascal, you will have
no problems porting from Turbo Pascal, or even Delphi, to Free Pascal.  To a large extent,
the constructs defined by Turbo Pascal are supported.  This is even more so if you use the
-So or -S2 switches.

In the following sections we will list the Turbo Pascal constructs which are not supported in
Free Pascal, and we will list in what ways Free Pascal extends the Turbo Pascal language.
6.1        Things  that  will  not  work


Here we give a list of things which are defined/allowed in Turbo Pascal, but which are not
supported by Free Pascal.  Where possible, we indicate the reason.


   1.  Duplicate case labels are not allowed.  This is a bug in Turbo Pascal and will not be
       changed.

   2.  Parameter  lists  of  previously  defined  functions  and  procedures  must  match  exactly.
       The reason for this is the function overloading mechanism of Free Pascal.  (however,
       the -So switch solves this.  See 5.1.5)

   3.  (*  ...    *) as comment delimiters are not allowed in versions older than 0.9.1.  This
       can easily be remedied with a grown-up editor.

   4.  The MEM,  MEMW,  MEML and PORT variables for memory and port access are not available
       in the system unit.  This is due to the operating system.  Under dos, the extender unit
       (GO32.PPU) implements the mem constuct.  under linux, the ports unit implements
       such a construct.

   5.  PROTECTED,  PUBLIC,  PUBLISHED,  TRY,  FINALLY,  EXCEPT,  RAISE are reserved words.
       This means you cannot create procedures or variables with the same name.  While they
       are not reserved words in Turbo Pascal, they are in Delphi.  Using the -So switch will
       solve this problem if you want to compile Turbo Pascal code that uses these words.

   6.  The  reserved  words  FAR,  NEAR  are  ignored.  This  is  because  Free  Pascal  is  a  32  bit
       compiler, so they're obsolete.



                                                             30

_________________________________________________________________________________6.2.___THINGS_WHICH_ARE_EXTRA_____________________*
 *___
   7.  INTERRUPT will work only on the dos target.

   8.  Boolean expressions are only evaluated until their result is completely determined.  The
       rest of the expression will be ignored.

   9.  By default the compiler uses AT&T assembler syntax.  This is mainly because Free Pascal
       uses gnu as.  However, other assembler forms are available.  For more information, see
       Programmers' guide.

  10.  Turbo Vision is not completely available.  There is FreeVision, but the degree of com-
       patibility with Turbo Vision is unclear at this time1 .

  11.  The 'overlay' unit is not available.  It also isn't necessary, since Free Pascal is a 32 bit
       compiler, so program size shouldn't be a point.

  12.  There are more reserved words.  (see appendix B for a list of all reserved words.)

  13.  The command-line parameters of the compiler are different.

  14.  Compiler switches and directives are mostly the same, but some extra exist.

  15.  Units are not binary compatible.

  16.  Sets  are  always  4  bytes  in  Free  Pascal;  this  means  that  some  typecasts  which  were
       possible in Turbo Pascal are no longer possible in Free Pascal.

  17.  A file is opened for output only (using fmOutput) when it is opened with Rewrite.  In
       order to be able to read from it, it should be reset with Reset.
6.2        Things  which  are  extra


Here  we  give  a  list  of  things  which  are  possible  in  Free  Pascal,  but  which  didn't  exist  in
Turbo Pascal or Delphi.


   1.  There are more reserved words.  (see appendix B for a list of all reserved words.)

   2.  Functions can also return complex types, such as records and arrays.

   3.  You can handle function results in the function itself, as a variable.  Example


       function  a  :  longint;


       begin
            a:=12;
            while  a>4  do
                begin
                     {...}
                end;
       end;


       The  example  above  would  work  with  TP,  but  the  compiler  would  assume  that  the
       a>4 is a recursive call.  To do a recursive call in this you must append () behind the
_______function_name:______________________________
    1At the time of writing, FreeVision has been taken off the net, because there are some copyright issues
which make it impossible to distribute it.


                                                                 31

_________________________________________________________________________________6.2.___THINGS_WHICH_ARE_EXTRA_____________________*
 *___
       function  a  :  longint;


       begin
            a:=12;
            {  this  is  the  recursive  call  }
            if  a()>4  then
                begin
                     {...}
                end;
       end;


   4.  There is partial support of Delphi constructs.  (see the Programmers' guide for more
       information on this).

   5.  The exit call accepts a return value for functions.


       function  a  :  longint;


       begin
            a:=12;
            if  a>4  then
                begin
                     exit(a*67);  {function  result  upon  exit  is  a*67  }
                end;
       end;


   6.  Free  Pascal  supports  function  overloading.   That  is,  you  can  define  many  functions
       with the same name, but with different arguments.  For example:


       procedure  DoSomething  (a  :  longint);
       begin
       {...}
       end;


       procedure  DoSomething  (a  :  real);
       begin
       {...}
       end;


       You can then call procedure DoSomething with an argument of type Longint or Real.
       This feature has the consequence that a previously declared function must always be
       defined with the header completely the same:


       procedure  x  (v  :  longint);  forward;


       {...}


       procedure  x;{  This  will  overload  the  previously  declared  x}
       begin
       {...}
       end;


       This construction will generate a compiler error, because the compiler didn't find a def-
       inition of  procedure  x  (v  :    longint);.  Instead you should define your procedure
       x as:



                                                                 32

______________________________________________________________6.3.___TURBO_PASCAL_COMPATIBILITY_MODE_______________________________*
 *___
       procedure  x  (v  :  longint);
       {  This  correctly  defines  the  previously  declared  x}
       begin
       {...}
       end;


       (The See 5.1.5 switch disables overloading.  When you use it, the above will compile,
       as in Turbo Pascal.

   7.  Operator overloading.  Free Pascal allows to overload operators, i.e.  you can define e.g.
       the '+' operator for matrices.

   8.  On FAT16 and FAT32 systems, long file names are supported.
6.3        Turbo  Pascal  compatibility  mode


When you compile a program with the -So switch, the compiler will attempt to mimic the
Turbo Pascal compiler in the following ways:


    o  Assigning a procedural variable doesn't require a @ operator.  One of the differences
       between  Turbo  Pascal  and  Free  Pascal  is  that  the  latter  requires  you  to  specify  an
       address  operator  when  assigning  a  value  to  a  procedural  variable.   In  Turbo  Pascal
       compatibility mode, this is not required.

    o  Procedure  overloading  is  disabled.  This  means  that  function  header  and  implemen-
       tation  can  be  different  (i.e.   the  function  iplementation  doesn't  need  to  repeat  the
       function header).

    o  Forward defined procedures don't need the full parameter list when they are defined.
       Due to the procedure overloading feature of Free Pascal, you must always specify the
       parameter list of a function when you define it, even when it was declared earlier with
       Forward.  In Turbo Pascal compatibility mode, there is no function overloading, hence
       you can omit the parameter list:


       Procedure  a  (L  :  Longint);  Forward;


       ...


       Procedure  a  ;  {  No  need  to  repeat  the  (L  :  Longint)  }


       begin
         ...
       end;



    o  recursive function calls are handled differently.  Consider the following example :


       Function  expr  :  Longint;


       begin
           ...
           Expr:=L:
           Writeln  (Expr);
           ...
       end;



                                                                 33

_______________________________________________________6.4.___A_NOTE_ON_LONG_FILE_NAMES_UNDER_DOS__________________________________*
 *___
       In Turbo Pascal compatibility mode, the function will be called recursively when the
       writeln statement is processed.  In Free Pascal, the function result will be printed.  In
       order  to  call  the  function  recusively  under  Free  Pascal,  you  need  to  implement  it  as
       follows :


       Function  expr  :  Longint;


       begin
           ...
           Expr:=L:
           Writeln  (Expr());
           ...
       end;


    o  Any text after the final End.  statement is ignored.  Normally,  this text is processed
       too.

    o  You cannot assign procedural variables to untyped pointers; so the following is invalid:


         a:  Procedure;
         b:  Pointer;
       begin
         b  :=  a;  //  Error  will  be  generated.


    o  The @ operator is typed when applied on procedures.

    o  You cannot nest comments.
6.4        A  note  on  long  file  names  under  dos


Under  Windows  32-bit  95  and  higher,  long  filenames  are  supported.  Compiling  for  the
win32 target ensures that long filenames are supported in all functions that do fie or disk
access in any way.

Moreover, Free Pascal supports the use of long filenames in the system unit and the dos unit
also for go32v2 executables.  The system unit contains the boolean variable LFNsupport.  If
it  is  set  to  True  then  all  system  unit  functions  and  DOS  unit  functions  will  use  long  file
names if they are available.  This should be so on all versions of Windows, with the possible
exception of Windows 32-bit 2000.  The system unit will check this by calling dos function
71A0h and checking whether long filenames are supported on the C: drive.

It  is  possible  to  disable  the  long  filename  support  by  setting  the  LFNSupport  variable  to
False.



                                                                 34


Chapter   7


Utilities   and   units   that   come



with   Free   Pascal



Besides the compiler and the Run-Time Library, Free Pascal comes with some utility pro-
grams and units.  Here we list these programs and units.
7.1        Demo  programs  and  examples


Also distributed with Free Pascal comes a series of demonstration programs.  These programs
have no other purpose than demonstrating the capabilities of Free Pascal.  They are located
in the demo directory of the sources.

All  example  programs  of  the  documentation  are  available.  Check  out  the  directories  that
end on ex in the documentation sources.  There you will find all example sources.
7.2        Supplied  programs



7.2.1       ppudump  program

ppudump is a program which shows the contents of a Free Pascal unit.  It is distributed with
the compiler.  You can just issue the following command


   ppudump  [options]  foo.ppu


to display the contents of the foo.ppu unit.  You can specify multiple files on the command
line.

The  options  can  be  used  to  change  the  verbosity  of  the  display.  By  default,  all  available
information is displayed.  You can set the verbosity level using the -Vxxx option.  Here, xxx
is a combination of the following letters:


h:   show header info.

i:  show interface information.

m:    show implementation information.

d:   show only (interface) definitions.
                                                             35

__________________________________________________________________________________________7.2.___SUPPLIED_PROGRAMS_________________*
 *___
s:   show only (interface) symbols.

b:   show browser info.

a:   show everything (default if no -V option is present).
7.2.2       ppumove  program

ppumove  is  a  program  to  make  shared  or  static  libraries  from  multiple  units.   It  can  be
compared with the tpumove program that comes with Turbo Pascal.

It should be distributed in binary form along with the compiler.

It's usage is very simple:


ppumove  [options]  unit1.ppu  unit2.ppu  ...  unitn.ppu


Where options is a combination of


-b:    If specified, ppumve will generate a batch file that will contain the external linking and
       archiving commands that must be executed.  The name of this batch file is pmove.sh
       on linux, and pmove.bat otherwise.

-d xxx:      If specified, the output files will put in the directory xxx

-e xxx:      Sets the extension of the moved unit files to xxx.  By default, this is .ppl.  You don't
       have to specify the dot.

-o xxx:      sets the name of the output file, i.e.  the name of the file containing all the units.
       This  parameter  is  mandatory  when  you  use  multiple  files.  On  linux,  ppumove  will
       prepend this name with lib if it isn't already there, and will add an extension appro-
       priate to the type of library.

-q:   Causes ppumove to operate silently.

-s:   Tells ppumove to make a static library instead of a dynamic one; By default a dynamic
       library is made on linux.

-w:    Tells ppumove that it is working under Windows NT. This will change the names of
       te linker and archiving program to ldw and arw, respectively.

-h or -?:      will display a short help.


The action of the ppumve program is as follows:  It takes each of the unit files, and modifies
it so that the compile will know that it should look for the unit code in the library.  The new
unit files will have an extension .ppu, this can be changed with the -e option.  It will then
put together all the object files of the units into one library, static or dynamic, depending
on the presence of the -s option.

The  name  of  this  library  must  be  set  with  the  -o  option.   If  needed,  the  prefix  lib  will
be prepended under linux..  The extension will be set to .a for static libraries,  for shared
libraries the extensions are .so on linux, and .dll under Windows NT and os/2.

As an example, the following command


./ppumove  -o  both  -e  ppl  ppu.ppu  timer.ppu


under linux, will generate the following output:

                                                                 36

__________________________________________________________________________________________7.2.___SUPPLIED_PROGRAMS_________________*
 *___
PPU-Mover  Version  0.99.7
Copyright  (c)  1998  by  the  Free  Pascal  Development  Team


Processing  ppu.ppu...  Done.
Processing  timer.ppu...  Done.
Linking  timer.o  ppu.o
Done.


And it will produce the following files:


   1.  libboth.so  :  The  shared  library  containing  the  code  from  ppu.o  and  timer.o.   Under
       Windows NT, this file would be called both.dll.

   2.  timer.ppl :  The unit file that tells the Free Pascal compiler to look for the timer code
       in the library.

   3.  ppu.ppl :  The unit file that tells the Free Pascal compiler to look for the timer code in
       the library.


You could then use or distribute the files libboth.so, timer.ppl and ppu.ppl.
7.2.3       ptop  -  Pascal  source  beautifier

ptop program


ptop  is  a  source  beautifier  written  by  Peter  Grogono  based  on  the  ancient  pretty-printer
by  Ledgard,  Hueras,  and  Singer,  modernized  by  the  Free  Pascal  team  (objects,  streams,
configurability etc)

This configurability, and the thorough bottom-up design are the advantages of this program
over the diverse TurboPascal sourcebeautifiers on e.g.  SIMTEL.

The program is quite simple to operate:

ptop "[-v] [-i indent] [-b bufsize ][-c optsfile] infile outfile"

The Infile parameter is the pascal file to be processed,  and will be written to outfile,  over-
writing an existing outfile if it exists.

Some options modify the behaviour of ptop:


-h  Writes an overview of the possible parameters and commandline syntax.

-c ptop.cfg      Read some configuration data from configuration file instead of using the inter-
       nal defaults then.  A config file is not required, the program can operate without one.
       See also -g.

-i ident    Sets the number of indent spaces used for BEGIN END; and other blocks.

-b bufsize      Sets the streaming buffersize to bufsize.  Default 255, 0 is considered non-valid
       and ignored.

-v  be  verbose.   Currently  only  outputs  the  number  of  lines  read/written  and  some  error
       messages.

-g  ptop.cfg     Writes a default configuration file to be edited to the file "ptop.cfg"
                                                                 37

__________________________________________________________________________________________7.2.___SUPPLIED_PROGRAMS_________________*
 *___

                                       Table 7.1:  keywords for operators


                      __Name_of_codeword______________operator________________________________________
                        casevar                      :  in a case label ( unequal 'colon')
                        becomes                      :=
                        delphicomment                //
                        opencomment                  { or (*
                        closecomment                 } or *)
                        semicolon                    ;
                        colon                        :
                        equals                       =
                        openparen                    [
                        closeparen                   ]
                        period                       .

The ptop configuration file


Creating and distributing a configuration file for ptop is not necesarry, unless you want to
modify the standard behaviour of  ptop.  The configuration file is never preloaded, so if you
want to use it you should always specify it with a -c  ptop.cfg parameter.

The structure of a ptop configuration file is a simple buildingblock repeated several (20-30)
times,  for each pascal keyword known to the ptop program.  (see the default configuration
file or ptopu.pp source to find out which keywords are known)

The basic building block of the configuration file consists out of one or two lines, describing
how ptop should react on a certain keyword.  First a line without square brackets with the
following format:

keyword=option1,option2,option3,...

If one of the options is "dindonkey" (see further below), a second line (with square brackets)
is needed like this:

[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...

As you can see the block contains two types of identifiers, keywords(keyword and otherkey-
word1..3 in above example) and options, (option1..3 above).

Keywords  are  the  built-in  valid  Pascal  structure-identifiers  like  BEGIN,  END,  CASE,  IF,
THEN, ELSE, IMPLEMENTATION. The default configuration file lists most of these.

Besides the real Pascal keywords, some other codewords are used for operators and comment
expressions.  table (7.1)

The Options codewords define actions to be taken when the keyword before the equal sign
is found, table (7.2)

The  option  "dindonkey"  requires  some  extra  parameters,  which  are  set  by  a  second  line
for that option (the one with the square brackets), which is therefore is only needed if the
options contain "dinkdonkey" (contraction of de-indent on assiociated keyword).

"dinkdonkey" deindents if any of the keywords specified by the extra options of the square-
bracket line is found.

Example:  The lines


else=crbefore,dindonkey,inbytab,upper
[else]=if,then,else
                                                                 38

__________________________________________________________________________________________7.2.___SUPPLIED_PROGRAMS_________________*
 *___

                                            Table 7.2:  Possible options


                         __Option____________does_what_____________________________________________
                           crsupp            suppress CR before the keyword.
                           crbefore          force CR before keyword
                                             (doesn't go with crsupp :)  )
                           blinbefore        blank line before keyword.
                           dindonkey         de-indent on associated keywords
                                             (see below)
                           dindent           deindent (always)
                           spbef             space before
                           spaft             space after
                           gobsym            Print symbols which follow a
                                             keyword but which do not
                                             affect layout.  prints until
                                             terminators occur.
                                             (terminators are hard-coded in pptop,
                                             still needs changing)
                           inbytab           indent by tab.
                           crafter           force CR after keyword.
                           upper             prints keyword all uppercase
                           lower             prints keyword all lowercase
                           capital           capitalizes keyword:  1st letter
                                             uppercase, rest lowercase.
mean the following:


    o  The keyword this block is about is else because it's on the LEFT side of both equal
       signs.

    o  The option crbefore signals not to allow other code (so just spaces) before the ELSE
       keyword on the same line.

    o  The option dindonkey de-indents if the parser finds any of the keywords in the square
       brackets line (if,then,else)

    o  The option inbytab means indent by a tab.

    o  The option upper uppercase the keyword (else or Else becomes ELSE)


Try to play with the configfile step by step until you find the effect you desire.  The config-
urability and possibilities of ptop are quite large.  E.g.  I like all keywords uppercased instead
of capitalized, so I replaced all capital keywords in the default file by upper.

ptop is still development software,  so it is wise to visually check the generated source and
try to compile it, to see if  ptop hasn't made any errors.



ptopu unit


The source of the PtoP program is conveniently split in two files:  One is a unit containing an
object that does the actual beautifying of the source, the other is a shell built around this
object so it can be used from the command line.  This design makes it possible to include
the object in some program (e.g.  an IDE) and use it's features to format code.

The object resided in the PtoPU unit, and is declared as follows



                                                                 39

__________________________________________________________________________________________7.2.___SUPPLIED_PROGRAMS_________________*
 *___
   TPrettyPrinter=Object(TObject)
         Indent  :  Integer;       {  How  many  characters  to  indent  ?  }
         InS       :  PStream;
         OutS     :  PStream;
         DiagS    :  PStream;
         CfgS  :  PStream;
         Constructor  Create;
         Function  PrettyPrint  :  Boolean;
      end;


Using this object is very simple.  The procedure is as follows:


   1.  Create the object, using it's constructor.

   2.  Set  the  Ins  stream.  This  is  an  open  stream,  from  which  pascal  source  will  be  read.
       This is a mandatory step.

   3.  Set  the  OutS  stream.  This  is  an  open  stream,  to  which  the  beautified  pascal  source
       will be written.  This is a mandatory step.

   4.  Set  the  DiagS  stream.  Any  diagnostics  will  be  written  to  this  stream.  This  step  is
       optional.  If you don't set this, no diagnostics are written.

   5.  Set the Cfgs stream.  A configuration is read from this stream.  (see the previous section
       for more information about configuration).  This step is optional.  If you don't set this,
       a default configuration is used.

   6.  Set  the  Indent  variable.  This  is  the  number  of  spaces  to  use  when  indenting.  Tab
       characters are not used in the program.  This step is optional.  The indent variable is
       initialized to 2.

   7.  Call  PrettyPrint.   This  will  pretty-print  the  source  in  Ins  and  write  the  result  to
       OutS. The function returns True if no errors occurred, False otherwise.


So, a minimal procedure would be:


Procedure  CleanUpCode;


var
   Ins,OutS  :  PBufStream;
   PPRinter  :  TPrettyPrinter;


begin
   Ins:=New(PBufStream,Init('ugly.pp',StopenRead,TheBufSize));
   OutS:=New(PBufStream,Init('beauty.pp',StCreate,TheBufSize));
   PPrinter.Create;
   PPrinter.Ins:=Ins;
   PPrinter.outS:=OutS;
   PPrinter.PrettyPrint;
end;


Using  memory  streams  allows  very  fast  formatting  of  code,  and  is  perfectly  suitable  for
editors.
                                                                 40

    ___________________________________________________________________________________________________7.3.___SUPPLIED_UNITS_______*
 *_______
    7.2.4       rstconv  program

    The rstconv program converts the resource string files generates by the compiler (when you
    use resource string sections) to .po files that can be understood by the GNU msgfmt program.

    Its usage is very easy; it accepts the following options:


    -i file  Use the specified file instead of stdin as input file.  This option is optional.

    -o file   write output to the specified file.  This option is required.

    -f format      Specifies the output format.  At the moment, only one output format is supported:
           po for GNU gettext .po format.  It is the default format.


    As an example:


    rstconv  -i  resdemo.rst  -o  resdemo.po


    will convert the resdemo.rst file to resdemo.po.

    More information on the rstconv utility can be found in the Programmers' guide, under the
    chapter about resource strings.
    7.2.5       fpcmake

    fpcmake is the Free Pascal makefile constructor program.

    It reads a Makefile.fpc configuration file and converts it to a Makefile suitable for reading by
    GNU make to compile your projects.  It is similar in functionality to GNU autoconf or Imake
    for making X projects.

    fpcmake accepts filenames of makefile description files as it's command-line arguments.  For
    each  of  these  files  it  will  create  a  Makefile  in  the  same  directory  where  the  file  is  located,
    overwriting any other existing file.

    If no options are given, it just attempts to read the file Makefile.fpc in the current directory
    and tries to construct a makefile from it.  any previously existing Makefile will be erased.

    The format of the fpcmake configuration file is described in great detail in the appendices of
    the Programmers' guide.
    7.3        Supplied  units


    Here we list the units that come with the Free Pascal distribution.  Since there is a difference
    in the supplied units per operating system,  we list them separately per system.  They are
    documented in the Unit reference.
    7.3.1       Units  common  to  all  platforms

    The following units are common to all platform; i.e.  their workings are guaranteed to be the
    same on all platforms.


getopts    This unit gives you the gnu getopts command-line arguments handling mechanism.
           It also supports long options.

   mmx     This unit provides support for mmx extensions in your code.

objects    This unit provides basic routines for handling objects.



                                                                     41

              ___________________________________________________________________________________________________7.3.___SUPPLIED_UN*
 *ITS______________
           objpas    is used for Delphi compatibility; you should never load this unit explicitly; it is auto-
                     matically loaded if you request Delphi mode.

             ports   provides access to the PC hardware ports.

           strings   This  unit  provides  basic  string  handling  routines  for  the  pchar  type,  comparable  to
                     similar routines in standard C libraries.

          sysutils   is an alternative implementation of the sysutils unit of Delphi.

          typinfo    Provides functions to acces Run-Time Type Information, just like Delphi.
              7.3.2       Under  DOS

                crt  This unit provides basic screen handling routines.  It provides the same functionality
                     as the Turbo Pascal CRT unit.

               dos   This unit provides basic routines for accessing the operating system dos.  It provides
                     almost the same functionality as the Turbo Pascal unit.

         emu387      This unit provides support for the coprocessor emulator.

            graph    This unit provides basic graphics handling, with routines to draw lines on the screen,
                     display texts etc.  It provides the same functions as the Turbo Pascal unit.

              go32   This unit provides access to possibilities of the GO32 dos extender.

          printer    This unit provides all you need for rudimentary access to the printer.
              7.3.3       Under  Windows

               dos   This unit provides basic routines for accessing the operating system dos.  It emulates
                     this functionality by issuing calls to the Windows operating system.

crt and wincrt       These units provides basic screen handling routines.  They provide the same function-
                     ality as the Turbo Pascal CRT unit.

            graph    This unit provides basic graphics handling, with routines to draw lines on the screen,
                     display texts etc.  It provides the same functions as the Turbo Pascal unit.

       Windows       This unit provides access to al Win32 API calls.  Effort has been taken to make sure
                     that  it  is  compatible  to  the  Delphi  version  of  this  unit,  so  code  for  Delphi  is  easily
                     ported to Free Pascal.

           opengl    provides access to the low-level opengl functions in Windows 32-bit.

      winmouse       provides access to the mouse in Windows 32-bit.

              ole2   provides access to the OLE capabilities of  Windows 32-bit.

         winsock     provides acces to the Windows 32-bit sockets API Winsock.

          sockets    is a wrapper around winsock that is compatible with the linux sockets layer.  Using
                     this unit ensures that your code will run both on Windows 32-bit and linux.



                                                                               42

      ___________________________________________________________________________________________________7.3.___SUPPLIED_UNITS_____*
 *_________
      7.3.4       Under  Linux

        crt  This unit provides basic screen handling routines.  It provides the same functionality
             Turbo  Pascal  CRT  unit.   It  should  work  on  any  terminal  which  supports  the  vt100
             escape sequences.

       dos   This unit provides an emulation of the same unit under dos.  It is intended primarily for
             easy porting of Pascal programs from dos to linux.  For good performance, however,
             it is recommended to use the linux unit.

     linux   This unit provides access to the linux operating system.  It provides most file and I/O
             handling  routines  that  you  may  need.  It  implements  most  of  the  standard  C  library
             constructs that you will find on a Unix system.  If you do a lot of disk/file operations,
             the use of this unit is recommended over the one you use under Dos.

  printer    This unit provides an interface to the standard Unix printing mechanism.  It supports
             printing to file and to any command you would like.

  sockets    This unit gives you access to sockets and TCP/IP programming.

    graph    Is an implementation of Borlands graph unit, which works on the Linux console.  It's
             implementation is as complete as on the other platforms (it shares the same code).  It
             uses the libvga and libvgagl graphics libraries, so you need these installed for this unit
             to work.  Also, programs using this library need to be run as root, or setuid root, and
             hence are a potential security risk.

     ports   This implements the various port[] constructs.  These are provided for compatibility
             only, and it is not recommended to use them extensively.  Programs using this construct
             must be run as ruit or setuid root, and are a serious security risk on your system.
      7.3.5       Under  OS/2

 doscalls    interface to doscalls.dll.

      dive   interface to dive.dll

      emx    provides access to the EMX extender.

      pm*    interface units for the program manager functions.

  viocalls   interface to viocalls.dll screen handling library.

moucalls     interface to moucalls.dll mouse handling library.

 kbdcalls    interface to kbdcalls.dll keyboard handling library.

moncalls     interface to moncalls.dll monitoring handling library.



                                                                       43


Chapter   8


Debugging   your   Programs



Free Pascal supports debug information for the gnu debugger gdb, or it's derivatives Insight
on win32 or ddd on linux.

This chapter describes shortly how to use this feature.  It doesn't attempt to describe com-
pletely  the  gnu  debugger,  however.   For  more  information  on  the  workings  of  the  gnu
debugger, see the gdb users' guide.

Free  Pascal  also  suports  gprof,  the  gnu  profiler,  see  section  8.4  for  more  information  on
profiling.
8.1        Compiling  your  program  with  debugger  support


First of all, you must be sure that the compiler is compiled with debugging support.  Unfor-
tunately, there is no way to check this at run time, except by trying to compile a program
with debugging support.

To compile a program with debugging support, just specify the -g option on the command-
line, as follows:


ppc386  -g  hello.pp


This  will  generate  debugging  information  in  the  executable  from  your  program.  You  will
notice that the size of the executable increases substantially because of this1 .

Note that the above will only generate debug information for the code that has been generated
when  compiling  hello.pp.   This  means  that  if  you  used  some  units  (the  system  unit,  for
instance) which were not compiled with debugging support,  no debugging support will be
available for the code in these units.

There are 2 solutions for this problem.


   1.  Recompile all units manually with the -g option.

   2.  Specify  the  'build'  option  (-B)  when  compiling  with  debugging  support.   This  will
       recompile all units, and insert debugging information in each of the units.


The second option may have undesirable side effects.  It may be that some units aren't found,
or compile incorrectly due to missing conditionals, etc..

If all went well, the executable now contains the necessary information with which you can
debug it using gnu gdb.
___________________________________________________1
     A good reason not to include debug information in an executable you plan to distribute.



                                                             44

        _______________________________________________________________8.2.___USING_GDB_TO_DEBUG_YOUR_PROGRAM______________________*
 *___________
        8.2        Using  gdb  to  debug  your  program


        To use gdb to debug your program, you can start the debugger, and give it as an option the
        full name of your program:


        gdb  hello


        Or, under dos:


        gdb  hello.exe


        This starts the debugger, and the debugger immediately loads your program into memory,
        but it does not run the program yet.  Instead, you are presented with the following (more or
        less) message, followed by the gdb prompt '(gdb)':


        GDB  is  free  software  and  you  are  welcome  to  distribute  copies  of  it
         under  certain  conditions;  type  "show  copying"  to  see  the  conditions.
        There  is  absolutely  no  warranty  for  GDB;  type  "show  warranty"  for  details.
        GDB  4.15.1  (i486-slackware-linux),
        Copyright  1995  Free  Software  Foundation,  Inc...
        (gdb)


        To start the program you can use the run command.  You can optionally specify command-
        line parameters, which will then be fed to your program, for example:


        (gdb)  run  -option  -anotheroption  needed_argument


        If your program runs without problems, gdb will inform you of this, and return the exit code
        of your program.  If the exit code was zero, then the message 'Program  exited  normally'.

        If something went wrong (a segmentation fault or so),  gdb will stop the execution of your
        program, and inform you of this with an appropriate message.  You can then use the other
        gdb commands to see what happened.  Alternatively, you can instruct gdb to stop at a certain
        point in your program, with the break command.

        Here  is  a  short  list  of  gdb  commands,  which  you  are  likely  to  need  when  debugging  your
        program:


        quit     Exits the debugger.

        kill   Stops a running program.

        help     Gives help on all gdb commands.

        file   Loads a new program into the debugger.

        directory        Add a new directory to the search path for source files.



Remark:         My copy of gdb needs '.'  to be added explicitly to the search path, otherwise it doesn't
               find the sources.

        list   Lists the program sources per 10 lines.  As an option you can specify a line number or
               function name.

        break      Sets a breakpoint at a specified line or function

        awatch       Sets a watch-point for an expression.  A watch-point stops execution of your pro-
               gram whenever the value of an expression is either read or written.



                                                                         45

______________________________________________________________8.3.___CAVEATS_WHEN_DEBUGGING_WITH_GDB_______________________________*
 *___
for more information, see the gdb users' guide, or use the 'help' function in gdb.

The appendix F contains a sample init file for gdb, which produces good results when de-
bugging Free Pascal programs.

It is also possible to use RHIDE, a text-based IDE that uses gdb.  There is a version of RHIDE
available that can work together with FPC.
8.3        Caveats  when  debugging  with  gdb


There are some peculiarities of Free Pascal which you should be aware of when using gdb.
We list the main ones here:


   1.  Free Pascal generates information for GDB in uppercare letters.  This is a consequence
       of the fact that pascal is a case insensitive language.  So, when referring to a variable
       or function, you need to make it's name all uppercase.

       As an example, of you want to watch the value of a loop variable count, you should
       type


       watch  COUNT


       Or if you want stop when a certain function (e.g MyFunction) is called, type


       break  MYFUNCTION


   2.  Line numbers may be off by a little.  This is a bug in Free Pascal and will be fixed as
       soon as possible.

   3.  gdb does not know sets.

   4.  gdb doesn't know strings.  Strings are represented in gdb as records with a length field
       and an array of char contaning the string.

       You can also use the following user function to print strings:


       define  pst
       set  $pos=&$arg0
       set  $strlen  =  {byte}$pos
       print  {char}&$arg0.st@($strlen+1)
       end


       document  pst
           Print  out  a  Pascal  string
       end


       If you insert it in your gdb.ini file, you can look at a string with this function.  There
       is a sample gdb.ini in appendix F.

   5.  Objects are difficult to handle,  mainly because gdb is oriented towards C and C++.
       The workaround implemented in Free Pascal is that object methods are represented as
       functions, with an extra parameter this (all lowercase !)  The name of this function is
       a concatenation of the object type and the function name, separated by two underscore
       characters.

       For example, the method TPoint.Draw would be converted to TPOINT_ _DRAW, and could
       be stopped at with



                                                                 46

__________________________________________________________8.4.___SUPPORT_FOR_GPROF,_THE_GNU_PROFILER_______________________________*
 *___
       break  TPOINT__DRAW


   6.  Global overloaded functions confuse gdb because they have the same name.  Thus you
       cannot set a breakpoint at an overloaded function, unless you know it's line number,
       in which case you can set a breakpoint at the starting linenumber of the function.
8.4        Support  for  gprof,  the  gnu  profiler


You  can  compile  your  programs  with  profiling  support.  for  this,  you  just  have  to  use  the
compiler switch -pg.  The compiler wil insert the necessary stuff for profiling.

When you have done this, you can run your program as you normally would run it.


yourexe


Where yourexe is the name of your executable.

When  your  program  finishes  a  file  called  gmon.out  is  generated.   Then  you  can  start  the
profiler to see the output.  You can better redirect the output to a file, becuase it could be
quite a lot:


gprof  yourexe  >  profile.log


Hint:  you can use the -flat option to reduce the amount of output of gprof.  It will then only
output the information about the timings

For more information on the gnu profiler gprof, see its manual.
8.5        Detecting  heap  memory  leaks


Free Pascal has a built in mechanism to detect memory leaks.  There is a plug-in unit for
the memory manager that analyses the memory allocation/deallocation and which prints a
memory usage report after the program exits.

The unit that does this is called heaptrc.  If you want to use it, you should include it as the
first unit in you uses clause.  Alternatively, you can supply the -gh switch to the compiler,
and it will include the unit automatically for you.

After the program exits, you will get a report looking like this:


Marked  memory  at  0040FA50  invalid
Wrong  size  :  128  allocated  64  freed
   0x00408708
   0x0040CB49
   0x0040C481
Call  trace  for  block  0x0040FA50  size  128
   0x0040CB3D
   0x0040C481


The output of the heaptrc unit is customizable by setting some variables.

You can find more information about the usage of the heaptrc unit in the Unit reference.

                                                                 47

___________________________________________8.6.___LINE_NUMBERS_IN_RUN-TIME_ERROR_BACKTRACES________________________________________*
 *___
8.6        Line  numbers  in  run-time  error  backtraces


Normally,  when  a  run-time  error  occurs,  you  are  presented  with  a  list  of  addresses  that
represent  the  call  stack  backtrace,  i.e.   the  addresses  of  all  procedures  that  were  invoked
when the run-time error occurred.

This list is not very informative, so there exists a unit that generates the file names and line
numbers  of  the  called  procedures  using  the  addresses  of  the  stack  backtrace.  This  unit  is
called lineinfo.

You can use this unit by giving the -gl option to the compiler.  The unit will be automatically
included.  It is also possible to use the unit explicitly in your uses clause, but you must make
sure that you compile your program with debug info.

Here is an example program:


program  testline;


procedure  generateerror255;


begin
   runerror(255);
end;


procedure  generateanerror;


begin
   generateerror255;
end;


begin
   generateanerror;
end.


When compiled with -gl, the following output is generated:


Runtime  error  255  at  0x0040BDE5
   0x0040BDE5    GENERATEERROR255,    line  6  of  testline.pp
   0x0040BDF0    GENERATEANERROR,    line  13  of  testline.pp
   0x0040BE0C    main,    line  17  of  testline.pp
   0x0040B7B1


Which is more understandable than the normal message.  Make sure that all units you use
are compiled with debug info, because if they are not, no line number and filename can be
found.
8.7        Combining  heaptrc  and  lineinfo


If you combine the lineinfo and the heaptrc information, then the output of the heaptrc unit
will contain the names of the files and line numbers of the procedures that occur in the stack
backtrace.

In such a case, the output will look something like this:


Marked  memory  at  00410DA0  invalid



                                                                 48

____________________________________________________________________8.7.___COMBINING_HEAPTRC_AND_LINEINFO__________________________*
 *___
Wrong  size  :  128  allocated  64  freed
   0x004094B8
   0x0040D8F9    main,    line  25  of  heapex.pp
   0x0040D231
Call  trace  for  block  0x00410DA0  size  128
   0x0040D8ED    main,    line  23  of  heapex.pp
   0x0040D231


If lines without filename/line-number occur, this means there is a unit which has no debug
info included.  (in the above case, the getmem call itself)
                                                                 49


Chapter   9


CGI   programming   in   Free



Pascal



In these days of heavy WWW traffic on the Internet, CGI scripts have become an important
topic in computer programming.  While CGI programming can be done with almost any tool
you wish, most languages aren't designed for it.  Perl may be a notable exception, but perl is
an interpreted language, the executable is quite big, and hence puts a big load on the server
machine.

Because of its simple,  almost intuitive,  string handling and its easy syntax,  Pascal is very
well suited for CGI programming.  Pascal allows you to quickly produce some results, while
giving you all the tools you need for more complex programming.  The basic RTL routines
in principle are enough to get the job done, but you can create, with relatively little effort,
some units which can be used as a base for more complex CGI programming.

That's why, in this chapter, we will discuss the basics of CGI in Free Pascal.  In the subse-
quent, we will assume that the server for which the programs are created, are based upon
the NCSA httpd WWW server, as the examples will be based upon the NCSA method of
CGI programming1 .  They have been tested with the apache server on linux, and the xitami
server on Windows NT.

The two example programs in this chapter have been tested on the command line and worked,
under  the  condition  that  no  spaces  were  present  in  the  name  and  value  pairs  provided  to
them.

There is however, a faster and generally better uncgi unit available, you can find it on the
contributed units page of the Free Pascal web site.  It uses techniques discussed here, but in
a generally more efficient way, and it also provides some extra functionality, not discussed
here.
9.1        Getting  your  data


Your CGI program must react on data the user has filled in on the form which your web-
server gave him.  The Web server takes the response on the form, and feeds it to the CGI
script.

There are essentially two ways of feeding the data to the CGI script.  We will discuss both.
___________________________________________________1
     ... and it's the only WWW-server I have to my disposition at the moment.



                                                             50

__________________________________________________________________________________________9.1.___GETTING_YOUR_DATA_________________*
 *___
9.1.1       Data  coming  through  standard  input.

The first method of getting your data is through standard input.  This method is invoked
when the form uses a form submission method of  POST. The web browser sets three envi-
ronment  variables  REQUEST_METHOD,  CONTENT_TYPE  and  CONTENT_LENGTH.  It  feeds  then  the
results  of  the  different  fields  through  standard  input  to  the  CGI  script.   All  the  Pascal
program has to do is :


    o  Check  the  value  of  the  REQUEST_METHOD  environment  variable.  The  getenv  function
       will retrieve this value this for you.

    o  Check the value of the CONTENT_TYPE environment variable.

    o  Read CONTENT_LENGTH characters from standard input.  read  (c) with c of type char
       will take care of that.


if  you  know  that  the  request  method  will  always  be  POST,  and  the  CONTENT_TYPE  will  be
correct,  then  you  can  skip  the  first  two  steps.   The  third  step  can  be  done  easier:  read
characters until you reach the end-of-file marker of standard input.

The following example shows how this can be achieved:


program  cgi_post;


uses  dos;


const  max_data  =  1000;


type  datarec  =  record
   name,value  :  string;
   end;


var  data  :  array[1..max_data]  of  datarec;
      i,nrdata  :  longint;
      c    :  char;
      literal,aname  :  boolean;


begin
writeln  ('Content-type:  text/html');
writeln;
if  getenv('REQUEST_METHOD')<>'POST'  then
    begin
    writeln  ('This  script  should  be  referenced  with  a  METHOD  of  POST');
    write  ('If  you  don''t  understand  this,  see  this  ');
    write  ('<  A  HREF="http://www.ncsa.uiuc.edu/SDG/Softare/Mosaic');
    writeln  ('/Docs/fill-out-forms/overview.html">forms  overview</A>.');
    halt(1);
    end;
if  getenv('CONTENT_TYPE')<>'application/x-www-form-urlencoded'  then
    begin
    writeln  ('This  script  can  only  be  used  to  decode  form  results');
    halt(1)
    end;
nrdata:=1;
aname:=true;
while  not  eof(input)  do



                                                                 51

__________________________________________________________________________________________9.1.___GETTING_YOUR_DATA_________________*
 *___
   begin
   literal:=false;
   read(c);
   if  c='\'  then
        begin
        literal:=true;
        read(c);
        end;
   if  literal  or  ((c<>'=')  and  (c<>'&'))  then
        with  data[nrdata]  do
             if  aname  then  name:=name+c  else  value:=value+c
   else
        begin
        if  c='&'  then
              begin
              inc  (nrdata);
              aname:=true;
              end
         else
              aname:=false;
         end
   end;
writeln  ('<H1>Form  Results  :</H1>');
writeln  ('You  submitted  the  following  name/value  pairs  :');
writeln  ('<UL>');
for  i:=1  to  nrdata  do  writeln  ('<LI>  ',data[i].name,'  =  ',data[i].value);
writeln  ('</UL>');
end.


While this program isn't shorter than the C program provided as an example at NCSA, it
doesn't need any other units.  everythig is done using standard Pascal procedures2 .

Note that this program has a limitation:  the length of names and values is limited to 255
characters.  This is due to the fact that strings in Pascal have a maximal length of 255.  It is
of course easy to redefine the datarec record in such a way that longer values are allowed.
In case you have to read the contents of a TEXTAREA form element, this may be needed.
9.1.2       Data  passed  through  an  environment  variable

If  your  form  uses  the  GET  method  of  passing  it's  data,  the  CGI  script  needs  to  read  the
QUERY_STRING environment variable to get it's data.  Since this variable can, and probably
will, be more than 255 characters long, you will not be able to use normal string methods,
present  in  pascal.   Free  Pascal  implements  the  pchar  type,  which  is  a  pointer  to  a  null-
terminated array of characters.  And, fortunately, Free Pascal has a strings unit, which eases
the use of the pchar type.

The following example illustrates what to do in case of a method of  GET


program  cgi_get;


uses  strings,linux;

___________________________________________________2
     actually, this program will give faulty results, since spaces in the input are converted to plus signs by
the web browser. The program doesn't check for this, but that is easy to change. The main concern here is
to give the working principle.



                                                                 52

__________________________________________________________________________________________9.1.___GETTING_YOUR_DATA_________________*
 *___
const  max_data  =  1000;


type  datarec  =  record
   name,value  :  string;
   end;


var  data  :  array[1..max_data]  of  datarec;
      i,nrdata  :  longint;
      p    :  PChar;
      literal,aname  :  boolean;


begin
Writeln  ('Content-type:  text/html');
Writeln;
if  StrComp(GetEnv('REQUEST_METHOD'),'POST')<>0  then
    begin
    Writeln  ('This  script  should  be  referenced  with  a  METHOD  of  GET');
    write  ('If  you  don''t  understand  this,  see  this  ');
    write  ('<  A  HREF="http://www.ncsa.uiuc.edu/SDG/Softare/Mosaic');
    Writeln  ('/Docs/fill-out-forms/overview.html">forms  overview</A>.');
    halt(1);
    end;
p:=GetEnv('QUERY_STRING');
nrdata:=1;
aname:=true;
while  p^<>#0    do
   begin
   literal:=false;
   if  p^='\'  then
        begin
        literal:=true;
        inc(longint(p));
        end;
   if  ((p^<>'=')  and  (p^<>'&'))  or  literal  then
        with  data[nrdata]  do
             if  aname  then  name:=name+p^  else  value:=value+p^
   else
        begin
        if  p^='&'  then
              begin
              inc  (nrdata);
              aname:=true;
              end
         else
              aname:=false;
         end;
   inc(longint(p));
   end;
Writeln  ('<H1>Form  Results  :</H1>');
Writeln  ('You  submitted  the  following  name/value  pairs  :');
Writeln  ('<UL>');
for  i:=1  to  nrdata  do  writeln  ('<LI>  ',data[i].name,'  =  ',data[i].value);
Writeln  ('</UL>');
end.



                                                                 53

___________________________________________________________________________________________9.2.___PRODUCING_OUTPUT_________________*
 *___
Although it may not be written in the most elegant way, this program does the same thing
as the previous one.  It also suffers from the same drawback,  namely the limited length of
the value field of the datarec.

This drawback can be remedied by redefining datarec as follows:


type  datarec  =  record;
         name,value  :  pchar;
        end;


and assigning at run time enough space to keep the contents of the value field.  This can be
done with a


 getmem  (data[nrdata].value,needed_number_of_bytes);


call.  After that you can do a


strlcopy  (data[nrdata].value,p,needed_number_of_bytes);


to copy the data into place.

You may have noticed the following unorthodox call :


inc(longint(p));


Free Pascal doesn't give you pointer arithmetic as in C. However, longints and pointers
have the same length (namely 4 bytes).  Doing a type-cast to a longint allows you to do
arithmetic on the pointer.

Note however, that this is a non-portable call.  This may work on the I386 processor, but not
on a ALPHA processor (where a pointer is 8 bytes long).  This will be remedied in future
releases of Free Pascal.
9.2        Producing  output


The  previous  section  concentrated  mostly  on  getting  input  from  the  web  server.  To  send
the  reply  to  the  server,  you  don't  need  to  do  anything  special.You  just  print  your  data
on  standard  output,  and  the  Web-server  will  intercept  this,  and  send  your  output  to  the
WWW-client waiting for it.

You can print anything you want, the only thing you must take care of is that you supply a
Contents-type line, followed by an empty line, as follows:


Writeln  ('Content-type:  text/html');
Writeln;
{  ...start  output  of  the  form...  }
And that's all there is to it !
9.3        I'm  under  Windows,  what  now  ?


Under Windows the system of writing CGI scripts can be totally different.  If you use Free
Pascal under Windows then you also should be able to do CGI programming, but the above
instructions may not work.  They are known to work for the xitami server, however.



                                                                 54

___________________________________________________________________9.3.___I'M_UNDER_WINDOWS,_WHAT_NOW_?____________________________*
 *___
If some kind soul is willing to write a section on CGI programming under Windows for other
servers, I'd be willing to include it here.


                                                                 55


Appendix   A


Alphabetical   listing   of



command-line   options



The following is alphabetical listing of all command-line options, as generated by the com-
piler:

ppc386  [options]  <inputfile>  [options]
put  +  after  a  boolean  switch  option  to  enable  it,  -  to  disable  it
   -a        the  compiler  doesn't  delete  the  generated  assembler  file
                  -al             list  sourcecode  lines  in  assembler  file
                  -ar             list  register  allocation/release  info  in  assembler  file
                  -at             list  temp  allocation/release  info  in  assembler  file
   -b        generate  browser  info
                  -bl             generate  local  symbol  info
   -B        build  all  modules
   -C<x>    code  generation  options:
                  -CD             create  also  dynamic  library  (not  supported)
                  -Ch<n>        <n>  bytes  heap  (between  1023  and  67107840)
                  -Ci             IO-checking
                  -Cn             omit  linking  stage
                  -Co             check  overflow  of  integer  operations
                  -Cr             range  checking
                  -Cs<n>        set  stack  size  to  <n>
                  -Ct             stack  checking
                  -CX             create  also  smartlinked  library
   -d<x>    defines  the  symbol  <x>
   -e<x>    set  path  to  executable
   -E        same  as  -Cn
   -F<x>    set  file  names  and  paths:
                  -FD<x>        sets  the  directory  where  to  search  for  compiler  utilities
                  -Fe<x>        redirect  error  output  to  <x>
                  -FE<x>        set  exe/unit  output  path  to  <x>
                  -Fi<x>        adds  <x>  to  include  path
                  -Fl<x>        adds  <x>  to  library  path
                  -FL<x>        uses  <x>  as  dynamic  linker
                  -Fo<x>        adds  <x>  to  object  path
                  -Fr<x>        load  error  message  file  <x>
                  -Fu<x>        adds  <x>  to  unit  path
                  -FU<x>        set  unit  output  path  to  <x>,  overrides  -FE



                                                             56

___________________________________________________________________________________________________________________________________*
 *___
   -g        generate  debugger  information:
                  -gg             use  gsym
                  -gd             use  dbx
                  -gh             use  heap  trace  unit  (for  memory  leak  debugging)
                  -gl             use  line  info  unit  to  show  more  info  for  backtraces
                  -gc             generate  checks  for  pointers
   -i        information
                  -iD             return  compiler  date
                  -iV             return  compiler  version
                  -iSO            return  compiler  OS
                  -iSP            return  compiler  processor
                  -iTO            return  target  OS
                  -iTP            return  target  processor
   -I<x>    adds  <x>  to  include  path
   -k<x>    Pass  <x>  to  the  linker
   -l        write  logo
   -n        don't  read  the  default  config  file
   -o<x>    change  the  name  of  the  executable  produced  to  <x>
   -pg       generate  profile  code  for  gprof  (defines  FPC_PROFILE)
   -P        use  pipes  instead  of  creating  temporary  assembler  files
   -S<x>    syntax  options:
                  -S2             switch  some  Delphi  2  extensions  on
                  -Sc             supports  operators  like  C  (*=,+=,/=  and  -=)
                  -sa             include  assertion  code.
                  -Sd             tries  to  be  Delphi  compatible
                  -Se<x>        compiler  stops  after  the  <x>  errors  (default  is  1)
                  -Sg             allow  LABEL  and  GOTO
                  -Sh             Use  ansistrings
                  -Si             support  C++  styled  INLINE
                  -Sm             support  macros  like  C  (global)
                  -So             tries  to  be  TP/BP  7.0  compatible
                  -Sp             tries  to  be  gpc  compatible
                  -Ss             constructor  name  must  be  init  (destructor  must  be  done)
                  -St             allow  static  keyword  in  objects
   -s        don't  call  assembler  and  linker  (only  with  -a)
   -u<x>    undefines  the  symbol  <x>
   -U        unit  options:
                  -Un             don't  check  the  unit  name
                  -Us             compile  a  system  unit
   -v<x>    Be  verbose.  <x>  is  a  combination  of  the  following  letters:
                  e  :  Show  errors  (default)            d  :  Show  debug  info
                  w  :  Show  warnings                         u  :  Show  unit  info
                  n  :  Show  notes                              t  :  Show  tried/used  files
                  h  :  Show  hints                              m  :  Show  defined  macros
                  i  :  Show  general  info                  p  :  Show  compiled  procedures
                  l  :  Show  linenumbers                    c  :  Show  conditionals
                  a  :  Show  everything                      0  :  Show  nothing  (except  errors)
                  b  :  Show  all  procedure                 r  :  Rhide/GCC  compatibility  mode
                        declarations  if  an  error       x  :  Executable  info  (Win32  only)
                        occurs
   -X        executable  options:
                  -Xc             link  with  the  c  library
                  -Xs             strip  all  symbols  from  executable
                  -XD             try  to  link  dynamic                 (defines  FPC_LINK_DYNAMIC)



                                                                 57

___________________________________________________________________________________________________________________________________*
 *___
                  -XS             try  to  link  static  (default)  (defines  FPC_LINK_STATIC)
                  -XX             try  to  link  smart                    (defines  FPC_LINK_SMART)


Processor  specific  options:
   -A<x>    output  format:
                  -Aas            assemble  using  GNU  AS
                  -Aasaout     assemble  using  GNU  AS  for  aout  (Go32v1)
                  -Anasmcoff  coff  (Go32v2)  file  using  Nasm
                  -Anasmelf    elf32  (Linux)  file  using  Nasm
                  -Anasmobj    obj  file  using  Nasm
                  -Amasm        obj  file  using  Masm  (Microsoft)
                  -Atasm        obj  file  using  Tasm  (Borland)
                  -Acoff        coff  (Go32v2)  using  internal  writer
                  -Apecoff     pecoff  (Win32)  using  internal  writer
   -R<x>    assembler  reading  style:
                  -Ratt          read  AT&T  style  assembler
                  -Rintel       read  Intel  style  assembler
                  -Rdirect     copy  assembler  text  directly  to  assembler  file
   -O<x>    optimizations:
                  -Og             generate  smaller  code
                  -OG             generate  faster  code  (default)
                  -Or             keep  certain  variables  in  registers
                  -Ou             enable  uncertain  optimizations  (see  docs)
                  -O1             level  1  optimizations  (quick  optimizations)
                  -O2             level  2  optimizations  (-O1  +  slower  optimizations)
                  -O3             level  3  optimizations  (same  as  -O2u)
                  -Op<x>        target  processor:
                                  -Op1    set  target  processor  to  386/486
                                  -Op2    set  target  processor  to  Pentium/PentiumMMX  (tm)
                                  -Op3    set  target  processor  to  PPro/PII/c6x86/K6  (tm)
   -T<x>    Target  operating  system:
                  -TGO32V1     version  1  of  DJ  Delorie  DOS  extender
                  -TGO32V2     version  2  of  DJ  Delorie  DOS  extender
                  -TLINUX       Linux
                  -TOS2          OS/2  2.x
                  -TWin32       Windows  32  Bit
   -W<x>    Win32  target  options
                  -WB<x>        Set  Image  base  to  Hexadecimal  <x>  value
                  -WC             Specify  console  type  application
                  -WD             Use  DEFFILE  to  export  functions  of  DLL  or  EXE
                  -WG             Specify  graphic  type  application
                  -WN             Do  not  generate  relocation  code  (necessary  for  debugging)
                  -WR             Generate  relocation  code


   -?        shows  this  help
   -h        shows  this  help  without  waiting

                                                                 58


Appendix   B


Alphabetical   list   of   reserved



words
absolute                                  file                                       packed
abstract                                  finally                                    popstack
and                                       for                                        private
array                                     forward                                    procedure
as                                        function                                   program
asm                                       goto                                       property
assembler                                 if                                         protected
begin                                     implementation                             public
break                                     in                                         raise
case                                      index                                      record
cdecl                                     inherited                                  repeat
class                                     initialization                             self
const                                     inline                                     set
constructor                               interface                                  shl
continue                                  interrupt                                  shr
destructor                                is                                         stdcall
dispose                                   label                                      string
div                                       library                                    then
do                                        mod                                        to
downto                                    name                                       true
else                                      near                                       try
end                                       new                                        type
except                                    nil                                        unit
exit                                      not                                        until
export                                    object                                     uses
exports                                   of                                         var
external                                  on                                         virtual
fail                                      operator                                   while
false                                     or                                         with
far                                       otherwise                                  xor
                                                             59


Appendix   C


Compiler   messages



This appendix is meant to list all the compiler messages.  The list of messages is generated
from he compiler source itself, and should be faitly complete.  At this point, only assembler
errors are not in the list.
C.1         General  compiler  messages


This section gives the compiler messages which are not fatal, but which display useful infor-
mation.  The number of such messages can be controlled with the various verbosity level -v
switches.


Compiler:  arg1          When the -vt switch is used, this line tells you what compiler is used.

Compiler OS: arg1              When the -vd switch is used, this line tells you what the source op-
       erating system is.

Info:  Target OS: arg1             When the -vd switch is used,  this line tells you what the target
       operating system is.

Using executable path:  arg1                  When the -vt switch is used, this line tells you where the
       compiler looks for it's binaries.

Using unit path:  arg1              When the -vt switch is used, this line tells you where the compiler
       looks for compiled units.  You can set this path with the -Fu

Using include path:  arg1               When  the  -vt  switch  is  used,  this  line  tells  you  where  the
       compiler  looks  for  it's  include  files  (files  used  in  {$I  xxx}  statements).  You  can  set
       this path with the -I option.

Using library path:  arg1               When  the  -vt  switch  is  used,  this  line  tells  you  where  the
       compiler looks for the libraries.  You can set this path with the -Fl option.

Using object path:  arg1               When the -vt switch is used, this line tells you where the com-
       piler looks for object files you link in (files used in {$L  xxx} statements).  You can set
       this path with the -Fo option.

Info:  arg1 Lines compiled, arg2 sec                     When the -vi switch is used, the compiler reports
       the  number  of  lines  compiled,  and  the  time  it  took  to  compile  them  (real  time,  not
       program time).


                                                             60

__________________________________________________________________________________________C.2.___SCANNER_MESSAGES._________________*
 *___
Fatal:  No memory left               The compiler doesn't have enough memory to compile your pro-
       gram.  There are several remedies for this:

           o  If you're using the build option of the compiler, try compiling the different units
              manually.

           o  If you're compiling a huge program, split it up in units, and compile these sepa-
              rately.

           o  If the previous two don't work, recompile the compiler with a bigger heap (you
              can use the -Ch option for this, See 5.1.4)

Info:  Writing Resource String Table file:  arg1                          This message is shown when the com-
       piler  writes  the  Resource  String  Table  file  containing  all  the  resource  strings  for  a
       program.

Error:  Writing Resource String Table file:  arg1                           This message is shown when the com-
       piler encountered an error when writing the Resource String Table file
C.2         Scanner  messages.


This section lists the messages that the scanner emits.  The scanner takes care of the lexical
structure of the pascal file, i.e.  it tries to find reserved words, strings, etc.  It also takes care
of directives and conditional compiling handling.


Fatal:  Unexpected end of file                 this typically happens in one of the following cases :

           o  The source file ends before the final end.  statement.  This happens mostly when
              the begin and end statements aren't balanced;

           o  An include file ends in the middle of a statement.

           o  A comment wasn't closed.

Fatal:  String exceeds line              You forgot probably to include the closing ' in a string, so it
       occupies multiple lines.

Fatal:  illegal character arg1 (arg2)                   An  illegal  character  was  encountered  in  the  input
       file.

Fatal:  Syntax error, arg1 expected but arg2 found                               This indicates that the compiler
       expected  a  different  token  than  the  one  you  typed.  It  can  occur  almost  everywhere
       where you make a mistake against the pascal language.

Start reading includefile arg1                 When you provide the -vt switch, the compiler tells you
       when it starts reading an included file.

Warning:  Comment level arg1 found                         When the -vw switch is used, then the compiler
       warns  you  if  it  finds  nested  comments.   Nested  comments  are  not  allowed  in  Turbo
       Pascal and can be a possible source of errors.

Note:  $F directive (FAR) ignored                      The FAR directive is a 16-bit construction which is
       recorgnised but ignored by the compiler, since it produces 32 bit code.

Note:  Stack check is global under Linux                         Stack checking with the -Cs switch is ignored
       under linux, since linux does this for you.  Only displayed when -vn is used.

Note:  Ignored compiler switch arg1                       With  -vn  on,  the  compiler  warns  if  it  ignores  a
       switch
                                                                 61

__________________________________________________________________________________________C.2.___SCANNER_MESSAGES._________________*
 *___
Warning:  Illegal compiler switch arg1                       You included a compiler switch (i.e.  {$...    })
       which the compiler doesn't know.

Warning:  This compiler switch has a global effect                              When  -vw  is  used,  the  compiler
       warns if a switch is global.

Error:  Illegal char constant               This happens when you specify a character with its ASCII
       code, as in #96, but the number is either illegal, or out of range.  The range is 1-255.

Fatal:  Can't open file arg1               Free Pascal cannot find the program or unit source file you
       specified on the command line.

Fatal:  Can't open include file arg1                    Free Pascal cannot find the source file you specified
       in a {$include  ..} statement.

Error:  Too many $ENDIFs or $ELSEs                            Your {$IFDEF  ..} and {$ENDIF} statements
       aren't balanced.

Warning:  Records fields can be aligned to 1,2,4,8,16 or 32 bytes only                                        You are spec-
       ifying the {$PACKRECORDS  n}   with an illegal value for n.  Only 1, 2, 4, 8, 16 and 32
       are valid in this case.

Warning:  Enumerated can be saved in 1,2 or 4 bytes only                                     You  are  specifying  the
       {$PACKENUM  n} with an illegal value for n.  Only 1,2 or 4 are valid in this case.

Error:  $ENDIF expected for arg1 arg2 defined in line arg3                                    Your conditional com-
       pilation statements are unbalanced.

Error:  Syntax error while parsing a conditional compiling expression                                         There is an
       error in the expression following the {$if  ..} compiler directive.

Error:  Evaluating a conditional compiling expression                                There  is  an  error  in  the  ex-
       pression following the {$if  ..} compiler directive.

Warning:  Macro contents is cut after char 255 to evalute expression                                         The contents
       of  macros  canno  be  longer  than  255  characters.  This  is  a  safety  in  the  compiler,  to
       prevent buffer overflows.  This is shown as a warning, i.e.  when the -vw switch is used.

Error:  ENDIF without IF(N)DEF                         Your {$IFDEF  ..} and {$ENDIF} statements aren't
       balanced.

Fatal:  User defined:  arg1              A user defined fatal error occurred.  see also the Programmers'
       guide

Error:  User defined:  arg1               A  user  defined  error  occurred.   see  also  the  Programmers'
       guide

Warning:  User defined:  arg1                  A  user  defined  warning  occurred.  see  also  the  Program-
       mers' guide

Note:  User defined:  arg1               A user defined note was encountered.  see also the Program-
       mers' guide

Hint:  User defined:  arg1              A  user  defined  hint  was  encountered.  see  also  the  Program-
       mers' guide

Info:  User defined:  arg1             User  defined  information  was  encountered.   see  also  the  Pro-
       grammers' guide

Error:  Keyword redefined as macro has no effect                               You cannot redefine keywords with
       macros.



                                                                 62

__________________________________________________________________________________________C.2.___SCANNER_MESSAGES._________________*
 *___
Fatal:  Macro buffer overflow while reading or expanding a macro                                        Your  macro  or
       it's result was too long for the compiler.

Warning:  Extension of macros exceeds a deep of 16.                                 When expanding a macro macros
       have been nested to a level of 16.  The compiler will expand no further, since this may
       be a sign that recursion is used.

Error:  compiler switches aren't allowed in (* ...  *) styled comments                                       Compiler switches
       should always be between {  } comment delimiters.

Handling switch "arg1"                 When  you  set  debugging  info  on  (-vd)  the  compiler  tells  you
       when it is evaluating conditional compile statements.

ENDIF arg1 found               When you turn on conditional messages(-vc), the compiler tells you
       where it encounters conditional statements.

IFDEF arg1 found, arg2                 When you turn on conditional messages(-vc), the compiler tells
       you where it encounters conditional statements.

IFOPT arg1 found, arg2                  When you turn on conditional messages(-vc), the compiler tells
       you where it encounters conditional statements.

IF arg1 found, arg2             When you turn on conditional messages(-vc), the compiler tells you
       where it encounters conditional statements.

IFNDEF arg1 found, arg2                   When  you  turn  on  conditional  messages(-vc),  the  compiler
       tells you where it encounters conditional statements.

ELSE arg1 found, arg2                When you turn on conditional messages(-vc), the compiler tells
       you where it encounters conditional statements.

Skipping until...         When  you  turn  on  conditional  messages(-vc),  the  compiler  tells  you
       where  it  encounters  conditional  statements,  and  whether  it  is  skipping  or  compiling
       parts.

Info:  Press <return> to continue                  When the -vi switch is used, the compiler stops com-
       pilation  and  waits  for  the  Enter  key  to  be  pressed  when  it  encounters  a  {$STOP}
       directive.

Warning:  Unsupported switch arg1                        When  warings  are  turned  on  (-vw)  the  compiler
       warns you about unsupported switches.  This means that the switch is used in Delphi
       or Turbo Pascal, but not in Free Pascal

Warning:  Illegal compiler directive arg1                       When warings are turned on (-vw) the com-
       piler  warns  you  about  unrecognised  switches.  For  a  list  of  recognised  switches,  Pro-
       grammers' guide

Back in arg1         When you use (-vt) the compiler tells you when it has finished reading an
       include file.

Warning:  Unsupported application type:  arg1                             You  get  this  warning,  ff  you  specify
       an unknown application type with the directive {$APPTYPE}

Warning:  APPTYPE isn't support by the target OS                                    The {$APPTYPE} directive is sup-
       ported by win32 applications only.

Warning:  DESCRIPTION is only supported for OS2 and Win32                                              The {$DESCRIPTION}
       directive is only supported for OS2 and Win32 targets.


                                                                 63

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Note:  VERSION is not supported by target OS.                                 The  {$VERSION}  directive  is  only
       supported by win32 target.

Note:  VERSION only for exes or DLLs                            The {$VERSION} directive is only used for ex-
       ecutable or DLL sources.

Warning:  Wrong format for VERSION directive arg1                                     The {$VERSION} directive for-
       mat is majorversion.minorversion where majorversion and minorversion are words.

Warning:  Unsupported assembler style specified arg1                                  When you specify an assem-
       bler mode with the {$ASMMODE  xxx} the compiler didn't recognize the mode you spec-
       ified.

Warning:  ASM reader switch is not possible inside asm statement, arg1 will be effective only for next
       It is not possible to switch from one assembler reader to another inside an assmebler
       block.  The new reader will be used for next assembler statement only.

Error:  Wrong switch toggle, use ON/OFF or +/-                                 You need to use ON or OFF or a
       + or - to toggle the switch

Error:  Resource files are not supported for this target                               The  target  you  are  compil-
       ing for doesn't support resource files.  The only targets which can use resource files are
       Win32 and OS/2 (EMX) currently

Warning:  Include environment arg1 not found in environment                                         The included envi-
       ronment  variable  can't  be  found  in  the  environment,  it'll  be  replaced  by  an  empty
       string instead.

Error:  Illegal value for FPU register limit                       Valid values for this directive are 0..8 and
       NORMAL/DEFAULT

Warning:  Only one resource file is supported for this target                                   The target you are com-
       piling for supports only one resource file.  This is the case of OS/2 (EMX) currently.
       The first resource file found is used, the others are discarded.
C.3         Parser  messages


This section lists all parser messages.  The parser takes care of the semantics of you language,
i.e.  it determines if your pascal constructs are correct.


Error:  Parser - Syntax Error                  An error against the Turbo Pascal language was encoun-
       tered.  This happens typically when an illegal character is found in the sources file.

Warning:  Procedure type FAR ignored                           This is a warning.  FAR is a construct for 8 or
       16 bit programs.  Since the compile generates 32 bit programs, it ignores this directive.

Warning:  Procedure type NEAR ignored                             This is a warning.  NEAR is a construct for
       8  or  16  bit  programs.   Since  the  compile  generates  32  bit  programs,  it  ignores  this
       directive.

Warning:  Procedure type INTERRUPT ignored for not i386                                           This is a warning.  INTERRUPT
       is a i386 specific construct and is ignored for other processors.

Error:  INTERRUPT procedure can't be nested                                  An  INTERRUPT  procedure  must  be
       global.

Warning:  Procedure type arg1 ignored                          This is a warning.  REGISTER,REINTRODUCE is
       ignored by FPC programs for now.  This is introduced first for Delphi compatibility.



                                                                 64

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Error:  Not all declarations of arg1 are declared with OVERLOAD                                           When you want
       to  use  overloading  using  the  OVERLOAD  directive,  then  all  declarations  need  to  have
       OVERLOAD specified.

Error:  No DLL File specified                  No longer in use.

Error:  Duplicate exported function name arg1                              Exported function names inside a spe-
       cific DLL must all be different

Error:  Duplicate exported function index arg1                             Exported function names inside a spe-
       cific DLL must all be different

Error:  Invalid index for exported function                         DLL function index must be in the range
       1..$FFFF

Warning:  Relocatable DLL or executable arg1 debug info does not work, disabled.



Warning:  To allow debugging for win32 code you need to disable relocation with -WN option
       Stabs info is wrong for relocatable DLL or EXES use -WN if you want to debug win32
       executables.

Error:  Constructor name must be INIT                           You are declaring a constructor with a name
       which isn't init, and the -Ss switch is in effect.  See the -Ss switch (See 5.1.5).

Error:  Destructor name must be DONE                             You are declaring a constructor with a name
       which isn't done, and the -Ss switch is in effect.  See the -Ss switch (See 5.1.5).

Error:  Illegal open parameter                  You are trying to use the wrong type for an open param-
       eter.

Error:  Procedure type INLINE not supported                               You tried to compile a program with
       C++  style  inlining,  and  forgot  to  specify  the  -Si  option  (See  5.1.5).   The  compiler
       doesn't support C++ styled inlining by default.

Warning:  Private methods shouldn't be VIRTUAL                                    You  declared  a  method  in  the
       private  part  of  a  object  (class)  as  virtual.   This  is  not  allowed.   Private  methods
       cannot be overridden anyway.

Warning:  Constructor should be public                          Constructors must be in the 'public' part of
       an object (class) declaration.

Warning:  Destructor should be public                         Destructors must be in the 'public' part of an
       object (class) declaration.

Note:  Class should have one destructor only                           You can declare only one destructor for
       a class.

Error:  Local class definitions are not allowed                         Classes must be defined globally.  They
       cannot be defined inside a procedure or function

Fatal:  Anonym class definitions are not allowed                            An invalid object (class) declaration
       was encountered, i.e.  an object or class without methods that isn't derived from another
       object or class.  For example:


         Type  o  =  object
                        a  :  longint;
                        end;

                                                                 65

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
       will trigger this error.

Error:  The object arg1 has no VMT

Error:  Illegal parameter list               You  are  calling  a  function  with  parameters  that  are  of  a
       different type than the declared parameters of the function.

Error:  Wrong parameter type specified for arg no.  arg1                                 There is an error in the pa-
       rameter list of the function or procedure.  The compiler cannot determine the error more
       accurate than this.

Error:  Wrong amount of parameters specified                              There is an error in the parameter list
       of the function or procedure, the number of parameters is not correct.

Error:  overloaded identifier arg1 isn't a function                           The  compiler  encountered  a  sym-
       bol with the same name as an overloaded function, but it isn't a function it can over-
       load.

Error:  overloaded functions have the same parameter list                                   You're declaring overloaded
       functions, but with the same parameter list.  Overloaded function must have at least 1
       different parameter in their declaration.

Error:  function header doesn't match the forward declaration arg1                                         You  declared
       a function with same parameters but different result type or function modifiers.

Error:  function header arg1 doesn't match forward :  var name changes arg2 => arg3
       You declared the function in the interface part, or with the forward directive, but
       define it with a different parameter list.

Note:  Values in enumeration types have to be ascending                                    Free Pascal allows enumer-
       ation constructions as in C. Given the following declaration two declarations:


         type  a  =  (A_A,A_B,A_E:=6,A_UAS:=200);
         type  a  =  (A_A,A_B,A_E:=6,A_UAS:=4);
       The second declaration would produce an error.  A_UAS needs to have a value higher
       than A_E, i.e.  at least 7.

Note:  Interface and implementation names are different arg1 => arg2                                            This  note
       warns you if the implementation and interface names of a functions are different, but
       they have the same mangled name.  This is important when using overloaded functions
       (but should produce no error).

Error:  With can not be used for variables in a different segment                                      With stores a vari-
       able  locally  on  the  stack,  but  this  is  not  possible  if  the  variable  belongs  to  another
       segment.

Error:  function nesting > 31                 You can nest function definitions only 31 times.

Error:  range check error while evaluating constants                               The  constants  are  out  of  their
       allowed range.

Warning:  range check error while evaluating constants                                  The constants are out of their
       allowed range.

Error:  duplicate case label               You  are  specifying  the  same  label  2  times  in  a  case  state-
       ment.

                                                                 66

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Error:  Upper bound of case range is less than lower bound                                     The upper bound of a
       case label is less than the lower bound and this is useless

Error:  typed constants of classes are not allowed                            You  cannot  declare  a  constant  of
       type class or object.

Error:  functions variables of overloaded functions are not allowed                                      You  are  trying
       to assign an overloaded function to a procedural variable.  This isn't allowed.

Error:  string length must be a value from 1 to 255                              The length of a string in Pascal
       is limited to 255 characters.  You are trying to declare a string with length lower than
       1 or greater than 255 (This is not true for Longstrings and AnsiStrings.

Warning:  use extended syntax of NEW and DISPOSE for instances of objects                                                    If
       you have a pointer a to a class type, then the statement new(a) will not initialize the
       class (i.e.  the constructor isn't called),  although space will be allocated.  you should
       issue the new(a,init) statement.  This will allocate space, and call the constructor of
       the class.

Warning:  use of NEW or DISPOSE for untyped pointers is meaningless

Error:  use of NEW or DISPOSE is not possible for untyped pointers                                            You cannot
       use new(p) or dispose(p) if  p is an untyped pointer because no size is associated to
       an untyped pointer.  Accepted for compatibility in tp and delphi modes.

Error:  class identifier expected                 This happens when the compiler scans a procedure dec-
       laration that contains a dot, i.e., a object or class method, but the type in front of the
       dot is not a known type.

Error:  type identifier not allowed here                      You cannot use a type inside an expression.

Error:  method identifier expected                     This identifier is not a method.  This happens when
       the compiler scans a procedure declaration that contains a dot, i.e., a object or class
       method, but the procedure name is not a procedure of this type.

Error:  function header doesn't match any method of this class                                      This identifier is not
       a method.  This happens when the compiler scans a procedure declaration that con-
       tains a dot, i.e., a object or class method, but the procedure name is not a procedure
       of this type.

procedure/function arg1                 When using the -vp switch, the compiler tells you when it starts
       processing a procedure or function implementation.

Error:  Illegal floating point constant                    The compiler expects a floating point expression,
       and gets something else.

Error:  FAIL can be used in constructors only                            You are using the FAIL instruction out-
       side a constructor method.

Error:  Destructors can't have parameters                          You are declaring a destructor with a pa-
       rameter list.  Destructor methods cannot have parameters.

Error:  Only class methods can be referred with class references                                      This error occurs
       in a situation like the following:


         Type  :
              Tclass  =  Class  of  Tobject;


         Var  C  :  TClass;



                                                                 67

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___


         begin
         ...
         C.free
       Free is not a class method and hence cannot be called with a class reference.

Error:  Only class methods can be accessed in class methods                                     This is related to the
       previous error.  You cannot call a method of an object from a inside a class method.
       The following code would produce this error:


         class  procedure  tobject.x;


         begin
            free
       Because free is a normal method of a class it cannot be called from a class method.

Error:  Constant and CASE types do not match                                One of the labels is not of the same
       type as the case variable.

Error:  The symbol can't be exported from a library                                You can only export procedures
       and functions when you write a library.  You cannot export variables or constants.

Warning:  An inherited method is hidden by arg1                                A method that is declared virtual
       in a parent class, should be overridden in the descendent class with the override di-
       rective.  If you don't specify the override directive, you will hide the parent method;
       you will not override it.

Error:  There is no method in an ancestor class to be overridden:  arg1                                         You try to
       override a virtual method of a parent class that doesn't exist.

Error:  No member is provided to access property                                You specified no read directive for
       a property.

Warning:  Stored prorperty directive is not yet implemented                                     The stored directive
       is not yet implemented

Error:  Illegal symbol for property access                        There is an error in the read or write direc-
       tives for an array property.  When you declare an array property, you can only access
       it with procedures and functions.  The following code woud cause such an error.


         tmyobject  =  class
            i  :  integer;
            property  x  [i  :  integer]:  integer  read  I  write  i;
Error:  Cannot access a protected field of an object here                                 Fields that are declared in
       a protected section of an object or class declaration cannot be accessed outside the
       module wher the object is defined, or outside descendent object methods.

Error:  Cannot access a private field of an object here                               Fields that are declared in a
       private section of an object or class declaration cannot be accessed outside the module
       where the class is defined.

                                                                 68

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Warning:  overloaded method of virtual method should be virtual:  arg1                                            If you de-
       clare  overloaded  methods  in  a  class,  then  they  should  either  all  be  virtual,  or  none.
       You shouldn't mix them.

Warning:  overloaded method of non-virtual method should be non-virtual:  arg1
       If you declare overloaded methods in a class, then they should either all be virtual, or
       none.  You shouldn't mix them.

Error:  overloaded methods which are virtual must have the same return type:  arg1
       If you declare virtual overloaded methods in a class definition, they must have the same
       return type.

Error:  EXPORT declared functions can't be nested                                  You  cannot  declare  a  function
       or procedure within a function or procedure that was declared as an export procedure.

Error:  methods can't be EXPORTed                          You cannot declare a procedure that is a method
       for an object as exported.  That is, your methods cannot be called from a C program.

Error:  call by var parameters have to match exactly:  Got arg1 expected arg2                                               When
       calling a function declared with var parameters, the variables in the function call must
       be of exactly the same type.  There is no automatic type conversion.

Error:  Class isn't a parent class of the current class                            When  calling  inherited  meth-
       ods, you are trying to call a method of a strange class.  You can only call an inherited
       method of a parent class.

Error:  SELF is only allowed in methods                         You  are  trying  to  use  the  self  parameter
       outside an object's method.  Only methods get passed the self parameters.

Error:  methods can be only in other methods called direct with type identifier of the class
       A construction like sometype.somemethod is only allowed in a method.

Error:  Illegal use of ':'           You are using the format :  (colon) 2 times on an expression that
       is not a real expression.

Error:  range check error in set constructor or duplicate set element                                       The declara-
       tion of a set contains an error.  Either one of the elements is outside the range of the
       set type, either two of the elements are in fact the same.

Error:  Pointer to object expected                     You specified an illegal type in a New statement.  The
       extended synax of  New needs an object as a parameter.

Error:  Expression must be constructor call                          When using the extended syntax of  new,
       you must specify the constructor method of the object you are trying to create.  The
       procedure you specified is not a constructor.

Error:  Expression must be destructor call                         When using the extended syntax of dispose,
       you must specify the destructor method of the object you are trying to dispose of.  The
       procedure you specified is not a destructor.

Error:  Illegal order of record elements                      When  declaring  a  constant  record,  you  speci-
       fied the fields in the wrong order.

Error:  Expression type must be class or record type                                A with statement needs an ar-
       gument that is of the type record or class.  You are using with on an expression that
       is not of this type.

Error:  Procedures can't return a value                        In Free Pascal, you can specify a return value
       for a function when using the exit statement.  This error occurs when you try to do
       this with a procedure.  Procedures cannot return a value.



                                                                 69

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Error:  constructors and destructors must be methods                                  You're declaring a procedure
       as destructor or constructor, when the procedure isn't a class method.

Error:  Operator is not overloaded                     You're trying to use an overloaded operator when it
       isn't overloaded for this type.

Error:  Impossible to overload assignment for equal types                                  You can not overload as-
       signment for types that the compiler considers as equal.

Error:  Impossible operator overload                      The combination of operator, arguments and re-
       turn type are incompatible.

Error:  Re-raise isn't possible there                   You are trying to raise an exception where it isn't
       allowed.  You can only raise exceptions in an except block.

Error:  The extended syntax of new or dispose isn't allowed for a class                                         You cannot
       generate an instance of a class with the extended syntax of new.  The constructor must
       be  used  for  that.   For  the  same  reason,  you  cannot  call  Dispose  to  de-allocate  an
       instance of a class, the destructor must be used for that.

Error:  Assembler incompatible with function return type                                    You're  trying  to  imple-
       ment a assembler function, but the return type of the function doesn't allow that.

Error:  Procedure overloading is switched off                          When using the -So switch,  procedure
       overloading is switched off.  Turbo Pascal does not support function overloading.

Error:  It is not possible to overload this operator (overload = instead)                                        You are try-
       ing to overload an operator which cannot be overloaded.  The following operators can
       be overloaded :


              +,  -,  *,  /,  =,  >,  <,  <=,  >=,  is,  as,  in,  **,  :=
Error:  Comparative operator must return a boolean value                                     When overloading the =
       operator, the function must return a boolean value.

Error:  Only virtual methods can be abstract                            You are declaring a method as abstract,
       when it isn't declared to be virtual.

Fatal:  Use of unsupported feature!                     You're trying to force the compiler into doing some-
       thing it cannot do yet.

Error:  The mix of CLASSES and OBJECTS isn't allowed                                         You cannot derive objects
       and classes intertwined .  That is, a class cannot have an object as parent and vice
       versa.

Warning:  Unknown procedure directive had to be ignored:  arg1                                         The procedure di-
       recive you secified is unknown.  Recognised procedure directives are cdecl, stdcall,
       popstack, pascal register, export.

Error:  absolute can only be associated to ONE variable                                  You cannot specify more than
       one variable before the absolute directive.  Thus, the following construct will provide
       this error:


         Var  Z  :  Longint;
                X,Y  :  Longint  absolute  Z;



                                                                 70

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
 absolute can only be associated a var or const                             The address of a absolute directive
       can  only  point  to  a  variable  or  constant.  Therefore,  the  following  code  will  produce
       this error:


            Procedure  X;


           var  p  :  longint  absolute  x;
Error:  absolute can only be associated a var or const                               The address of a absolute di-
       rective  can  only  point  to  a  variable  or  constant.   Therefore,  the  following  code  will
       produce this error:


            Procedure  X;


           var  p  :  longint  absolute  x;
Error:  Only ONE variable can be initialized                           You cannot specify more than one vari-
       able with a initial value in Delphi syntax.

Error:  Abstract methods shouldn't have any definition (with function body)                                               Abstract
       methods can only be declared, you cannot implement them.  They should be overridden
       by a descendant class.

Error:  This overloaded function can't be local (must be exported)                                        You are defin-
       ing a overloaded function in the implementation part of a unit, but there is no corre-
       sponding declaration in the interface part of the unit.

Warning:  Virtual methods are used without a constructor in arg1                                          If  you  declare
       objects  or  classes  that  contain  virtual  methods,  you  need  to  have  a  constructor  and
       destructor to initialize them.  The compiler encountered an object or class with virtual
       methods that doesn't have a constructor/destructor pair.

Macro defined:  arg1             When -vm is used, the compiler tells you when it defines macros.

Macro undefined:  arg1               When -vm is used, the compiler tells you when it undefines macros.

Macro arg1 set to arg2               When -vm is used, the compiler tells you what values macros get.

Info:  Compiling arg1             When you turn on information messages (-vi), the compiler tells
       you what units it is recompiling.

Parsing interface of unit arg1                  This  tells  you  that  the  reading  of  the  interface  of  the
       current unit starts

Parsing implementation of arg1                     This tells you that the code reading of the implemen-
       tation of the current unit, library or program starts

Compiling arg1 for the second time                       When you request debug messages (-vd) the com-
       piler tells you what units it recompiles for the second time.

Error:  Array properties aren't allowed here                          You cannot use array properties at that
       point in the source.

Error:  No property found to override                       You  want  to  overrride  a  property  of  a  parent
       class, when there is, in fact, no such property in the parent class.

                                                                 71

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Error:  Only one default property is allowed, found inherited default property in class arg1
       You specified a property as Default, but a parent class already has a default property,
       and a class can have only one default property.

Error:  The default property must be an array property                                   Only array properties of classes
       can be made default properties.

Error:  Virtual constructors are only supported in class object model                                         You cannot
       have virtual constructors in objects.  You can only have them in classes.

Error:  No default property available                      You  try  to  access  a  default  property  of  a  class,
       but this class (or one of it's ancestors) doesn't have a default property.

Error:  The class can't have a published section, use the $M+ switch                                          If you want
       a published section in a class definition, you must use the {$M+} switch, whch turns
       on generation of type information.

Error:  Forward declaration of class arg1 must be resolved here to use the class as ancestor
       To be able to use an object as an ancestor object, it must be defined first.  This error
       occurs in the following situation:


           Type  ParentClas  =  Class;
                   ChildClass  =  Class(ParentClass)
                      ...
                   end;
       Where ParentClass is declared but not defined.

Error:  Local operators not supported                       You  cannot  overload  locally,  i.e.  inside  proce-
       dures or function definitions.

Error:  Procedure directive arg1 not allowed in interface section                                     This procedure di-
       rective is not allowed in the interface section of a unit.  You can only use it in the
       implementation section.

Error:  Procedure directive arg1 not allowed in implementation section                                           This pro-
       cedure directive is not defined in the implementation section of a unit.  You can only
       use it in the interface section.

Error:  Procedure directive arg1 not allowed in procvar declaration                                        This procedure
       directive cannot be part of a procedural or function type declaration.

Error:  Function is already declared Public/Forward arg1                                   You will get this error if
       a  function  is  defined  as  forward  twice.  Or  it  is  once  in  the  interface  section,  and
       once as a forward declaration in the implmentation section.

Error:  Can't use both EXPORT and EXTERNAL                                       These  two  procedure  directives
       are mutually exclusive

Error:  NAME keyword expected                        The  definition  of  an  external  variable  needs  a  name
       clause.

Warning:  arg1 not yet supported inside inline procedure/function                                         Inline procedures
       don't support this declaration.

Warning:  Inlining disabled                Inlining of procedures is disabled.

Info:  Writing Browser log arg1                   When information messages are on, the compiler warns
       you when it writes the browser log (generated with the {$Y+  } switch).



                                                                 72

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Hint:  may be pointer dereference is missing                           The compiler thinks that a pointer may
       need a dereference.

Fatal:  Selected assembler reader not supported                             The selected assembler reader (with
       {$ASMMODE  xxx}  is  not  supported.   The  compiler  can  be  compiled  with  or  without
       support for a particular assembler reader.

Error:  Procedure directive arg1 has conflicts with other directives                                      You specified a
       procedure directive that conflicts with other directives.  for instance cdecl and pascal
       are mutually exclusive.

Error:  Calling convention doesn't match forward                              This  error  happens  when  you  de-
       clare a function or procedure with e.g.  cdecl;  but omit this directive in the imple-
       mentation,  or  vice  versa.  The  calling  convention  is  part  of  the  function  declaration,
       and must be repeated in the function definition.

Error:  Register calling (fastcall) not supported                          The register calling convention, i.e.,
       arguments are passed in registers instead of on the stack is not supported.  Arguments
       are always passed on the stack.

Error:  Property can't have a default value                         Set properties or indexed properties can-
       not have a default value.

Error:  The default value of a property must be constant                                  The  value  of  a  default
       declared  property  must  be  known  at  compile  time.   The  value  you  specified  is  only
       known  at  run  time.   This  happens  .e.g.   if  you  specify  a  variable  name  as  a  default
       value.

Error:  Symbol can't be published, can be only a class                                Only class type variables can
       be in a published section of a class if they are not declared as a property.

Error:  That kind of property can't be published                             Properties  in  a  published  section
       cannot  be  array  properties.  they  must  be  moved  to  public  sections.  Properties  in  a
       published section must be an ordinal type, a real type, strings or sets.

Warning:  Empty import name specified                           Both index and name for the import are 0 or
       empty

Warning:  An import name is required                          Some  targets  need  a  name  for  the  imported
       procedure or a cdecl specifier

Error:  Function internal name changed after use of function                                    This is an internal er-
       ror; please report any occurrences of this error to the Free Pascal team.

Error:  Division by zero              There is a divsion by zero encounted

Error:  Invalid floating point operation                      An operation on two real type values produced
       an overflow or a division by zero.

Error:  Upper bound of range is less than lower bound                                  The upper bound of a case
       label is less than the lower bound and this is not possible

Warning:  string "arg1" is longer than arg2                          The  size  of  the  constant  string  is  larger
       than the size you specified in string type definition

Error:  string length is larger than array of char length                               The size of the constant string
       is larger than the size you specified in the array[x..y] of char definition

Error:  Illegal expression after message directive                           Free Pascal supports only integer or
       string values as message constants



                                                                 73

______________________________________________________________________________________________C.3.___PARSER_MESSAGES_______________*
 *___
Error:  Message handlers can take only one call by ref.  parameter                                       A method declared
       with the message-directive as message handler can take only one parameter which must
       be declared as call by reference Parameters are declared as call by reference using the
       var-directive

Error:  Duplicate message label:  arg1                      A  label  for  a  message  is  used  twice  in  one  ob-
       ject/class

Error:  Self can be only an explicit parameter in message handlers                                       The self param-
       eter can be passed only explicitly in a method which is declared as message method
       handler.

Error:  Threadvars can be only static or global                           Threadvars must be static or global,
       you can't declare a thread local to a procedure.  Local variables are always local to a
       thread, because every thread has it's own stack and local variables are stored on the
       stack

Fatal:  Direct assembler not supported for binary output format                                       You can't use di-
       rect  assembler  when  using  a  binary  writer,  choose  an  other  outputformat  or  use  an
       other assembler reader

Warning:  Don't load OBJPAS unit manual, use $mode objfpc or $mode delphi instead
       You're trying to load the ObjPas unit manual from a uses clause.  This is not a good
       idea to do, you can better use the {$mode  objfpc} or {$mode  delphi} directives which
       load the unit automaticly

Error:  OVERRIDE can't be used in objects                              Override  isn't  support  for  objects,  use
       VIRTUAL instead to override a method of an anchestor object

Error:  Data types which requires initialization/finalization can't be used in variant records
       Some data type (e.g.  ansistring) needs initialization/finalization code which is im-
       plicitly generated by the compiler.  Such data types can't be used in the variant part
       of a record.

Error:  Resourcestrings can be only static or global                              Resourcestring can not be declared
       local, only global or using the static directive.

Error:  Exit with argument can't be used here                             an  exit  statement  with  an  argument
       for  the  return  value  can't  be  used  here,  this  can  happen  e.g.   in  try..except  or
       try..finally blocks

Error:  The type of the storage symbol must be boolean                                   If you specify a storage sym-
       bol in a property declaration, it must be of the type boolean

Error:  This symbol isn't allowed as storage symbol                               You can't use this type of sym-
       bol as storage specifier in property declaration.  You can use only methods with the
       result type boolean, boolean class fields or boolean constants

Error:  Only class which are compiled in $M+ mode can be published                                             In the pub-
       lished section of a class can be only class as fields used which are compiled in {$M+}
       or which are derived from such a class.  Normally such a class should be derived from
       TPersitent

Error:  Procedure directive expected                       When declaring a procedure in a const block you
       used a ; after the procedure declaration after which a procedure directive must follow.
       Correct declarations are:



                                                                 74

___________________________________________________________________________________C.4.___TYPE_CHECKING_ERRORS_____________________*
 *___
         const
            p  :  procedure;stdcall=nil;
            p  :  procedure  stdcall=nil;
Error:  The value for a property index must be of an ordinal type                                        The  value  you
       use  to  index  a  property  must  be  of  an  ordinal  type,  for  example  an  integer  or  enu-
       merated type.

Error:  Procedure name to short to be exported                               The length of the procedure/function
       name  must  be  at  least  2  characters  long.  This  is  because  of  a  bug  in  dlltool  which
       doesn't parse the .def file correct with a name of length 1.

Error:  No DEFFILE entry can be generated for unit global vars

Error:  Compile without -WD option
C.4         Type  checking  errors


This section lists all errors that can occur when type checking is performed.


Error:  Type mismatch                This can happen in many cases:

           o  The variable you're assigning to is of a different type than the expression in the
              assignment.

           o  You  are  calling  a  function  or  procedure  with  parameters  that  are  incompatible
              with the parameters in the function or procedure definition.

Error:  Incompatible types:  got "arg1" expected "arg2"                                  There is no conversion pos-
       sible  between  the  two  types  Another  possiblity  is  that  they  are  declared  in  different
       declarations:


         Var
              A1  :  Array[1..10]  Of  Integer;
              A2  :  Array[1..10]  Of  Integer;


         Begin
              A1:=A2;  {  This  statement  gives  also  this  error,  it
                              is  due  the  strict  type  checking  of  pascal  }
         End.
Error:  Type mismatch between arg1 and arg2                               The types are not equal

Error:  Type identifier expected                   The identifier is not a type, or you forgot to supply a
       type identifier.

Error:  Variable identifier expected                    This  happens  when  you  pass  a  constant  to  a  Inc
       var or Dec procedure.  You can only pass variables as arguments to these functions.

Error:  Integer expression expected, but got "arg1"                               The compiler expects an expres-
       sion of type integer, but gets a different type.

Error:  Boolean expression expected, but got "arg1"                                 The expression must be a boolean
       type, it should be return true or false.
                                                                 75

___________________________________________________________________________________C.4.___TYPE_CHECKING_ERRORS_____________________*
 *___
Error:  Ordinal expression expected                      The expression must be of ordinal type, i.e., max-
       imum a Longint.  This happens, for instance, when you specify a second argument to
       Inc or Dec that doesn't evaluate to an ordinal value.

Error:  pointer type expected, but got "arg1"                            The variable or expression isn't of the
       type pointer.  This happens when you pass a variable that isn't a pointer to New or
       Dispose.

Error:  class type expected, but got "arg1"                          The variable of expression isn't of the type
       class.  This happens typically when

          1.  The parent class in a class declaration isn't a class.

          2.  An exception handler (On) contains a type identifier that isn't a class.

Error:  Variable or type indentifier expected                          The argument to the High or Low func-
       tion is not a variable nor a type identifier.

Error:  Can't evaluate constant expression                         No longer in use.

Error:  Set elements are not compatible                        You are trying to make an operation on two
       sets, when the set element types are not the same.  The base type of a set must be the
       same when taking the union

Error:  Operation not implemented for sets                           several binary operations are not defined
       for sets like div mod ** (also >= <= for now)

Warning:  Automatic type conversion from floating type to COMP which is an integer type
       An implicit type conversion from a real type to a comp is encountered.  Since Comp is a
       64 bit integer type, this may indicate an error.

Hint:  use DIV instead to get an integer result                           When  hints  are  on,  then  an  integer
       division with the '/' operator will procuce this message,  because the result will then
       be of type real

Error:  string types doesn't match, because of $V+ mode                                    When compiling in {$V+}
       mode, the string you pass as a parameter should be of the exact same type as the de-
       clared parameter of the procedure.

Error:  succ or pred on enums with assignments not possible                                     When you declared an
       enumeration type which has assignments in it, as in C, like in the following:


            Tenum  =  (a,b,e:=5);
       you cannot use the Succ or Pred functions on them.

Error:  Can't read or write variables of this type                           You are trying to read or write a
       variable from or to a file of type text, which doesn't support that.  Only integer types,
       booleans, reals, pchars and strings can be read from/written to a text file.

Error:  Can't use readln or writeln on typed file                           readln and writeln are only allowed
       for text files.

Error:  Can't use read or write on untyped file.                           read and write are only allowed for
       text or typed files.

Error:  Type conflict between set elements                          There is at least one set element which is
       of the wrong type, i.e.  not of the set type.
                                                                 76

_____________________________________________________________________________________________C.5.___SYMBOL_HANDLING________________*
 *___
Warning:  lo/hi(dword/qword) returns the upper/lower word/dword                                              Free  Pascal
       supports an overloaded version of  lo/hi for longint/dword/int64/qword which re-
       turns the lower/upper word/dword of the argument.  TP always uses a 16 bit lo/hi
       which  returns  always  bits  0..7  for  lo  and  the  bits  8..15  for  hi.  If  you  want  the  TP
       behavior you have to type cast the argument to word/integer

Error:  Integer or real expression expected                         The first argument to str must a real or
       integer type.

Error:  Wrong type arg1 in array constructor                            You are trying to use a type in an array
       constructor which is not allowed.

Error:  Incompatible type for arg no.  arg1:  Got arg2, expected arg3                                       You are try-
       ing to pass an invalid type for the specified parameter.

Error:  Method (variable) and Procedure (variable) are not compatible                                            You can't
       assign a method to a procedure variable or a procedure to a method pointer.

Error:  Illegal constant passed to internal math function                                The constant argument passed
       to a ln or sqrt function is out of the definition range of these functions.

Error:  Can't get the address of constants                        It's not possible to get the address of a con-
       stant, because they aren't stored in memory, you can try making it a typed constant.

Error:  Argument can't be assigned to                        Only expressions which can be on the left side
       of an assignment can be passed as call by reference argument Remark:  Properties can
       be only used on the left side of an assignment, but they can't be used as arguments

Error:  Can't assign local procedure/function to procedure variable                                        It's not allowed
       to assign a local procedure/function to a procedure variable, because the calling of lo-
       cal procedure/function is different.  You can only assign local procedure/function to a
       void pointer.

Error:  Can't assign values to an address                        It's not allowed to assign a value to an ad-
       dress of a variable,constant, procedure or function.  You can try compiling with -So if
       the identifier is a procedure variable.

Error:  Can't assign values to const variable                         It's  not  allowed  to  assign  a  value  to  a
       variable which is declared as a const.  This is normally a parameter declared as const,
       to allow changing make the parameter value or var.
C.5         Symbol  handling


This  section  lists  all  the  messages  that  concern  the  handling  of  symbols.   This  means  all
things that have to do with procedure and variable names.


Error:  Identifier not found arg1                  The compiler doesn't know this symbol.  Usually hap-
       pens  when  you  misspel  the  name  of  a  variable  or  procedure,  or  when  you  forgot  to
       declare a variable.

Fatal:  Internal Error in SymTableStack()                         An internal error occurred in the compiler;
       If  you  encounter  such  an  error,  please  contact  the  developers  and  try  to  provide  an
       exact description of the circumstances in which the error occurs.

Error:  Duplicate identifier arg1                  The identifier was already declared in the current scope.

Hint:  Identifier already defined in arg1 at line arg2                            The  identifier  was  already  de-
       clared in a previous scope.



                                                                 77

_____________________________________________________________________________________________C.5.___SYMBOL_HANDLING________________*
 *___
Error:  Unknown identifier arg1                    The identifier encountered hasn't been declared,  or is
       used outside the scope where it's defined.

Error:  Forward declaration not solved arg1                          This can happen in two cases:

           o  This  happens  when  you  declare  a  function  (in  the  interface  part,  or  with  a
              forward directive, but do not implement it.

           o  You reference a type which isn't declared in the current type block.

Fatal:  Identifier type already defined as type                         You are trying to redefine a type.

Error:  Error in type definition                 There is an error in your definition of a new array type:

 One  of  the  range  delimiters  in  an  array  declaration  is  erroneous.   For  example,  Array
       [1..1.25] will trigger this error.

Error:  Type identifier not defined                    The type identifier has not been defined yet.

Error:  Forward type not resolved arg1                        A  symbol  was  forward  defined,  but  no  decla-
       ration was encountered.

Error:  Only static variables can be used in static methods or outside methods                                               A
       static method of an object can only access static variables.

Error:  Invalid call to tvarsym.mangledname()                            An internal error occurred in the com-
       piler; If you encounter such an error, please contact the developers and try to provide
       an exact description of the circumstances in which the error occurs.

Fatal:  record or class type expected                     The variable or expression isn't of the type record
       or class.

Error:  Instances of classes or objects with an abstract method are not allowed
       You are trying to generate an instance of a class which has an abstract method that
       wasn't overridden.

Warning:  Label not defined arg1                     A label was declared, but not defined.

Error:  Label used but not defined arg1                        A  label  was  declared  and  used,  but  not  de-
       fined.

Error:  Illegal label declaration                This  error  should  never  happen;  it  occurs  if  a  label  is
       defined outside a procedure or function.

Error:  GOTO and LABEL are not supported (use switch -Sg)                                          You  must  compile
       a  program  which  has  labels  and  goto  statements  with  the  -Sg  switch.  By  default,
       label and goto aren't supported.

Error:  Label not found               A goto  label was encountered, but the label isn't declared.

Error:  identifier isn't a label              The identifier specified after the goto isn't of type label.

Error:  label already defined                You are defining a label twice.  You can define a label only
       once.

Error:  illegal type declaration of set elements                         The  declaration  of  a  set  contains  an
       invalid type definition.

Error:  Forward class definition not resolved arg1                            You declared a class, but you didn't
       implement it.

Hint:  Unit arg1 not used in arg2                    The unit referenced in the uses clause is not used.



                                                                 78

____________________________________________________________________________C.6.___CODE_GENERATOR_MESSAGES_________________________*
 *___
Hint:  Parameter arg1 not used                    This is a warning.  The identifier was declared (locally
       or globally) but wasn't used (locally or globally).

Note:  Local variable arg1 not used                     You  have  declared,  but  not  used  a  variable  in  a
       procedure or function implementation.

Hint:  Value parameter arg1 is assigned but never used                                  This is a warning.  The iden-
       tifier was declared (locally or globally) set but not used (locally or globally).

Note:  Local variable arg1 is assigned but never used                               The variable in a procedure or
       function implementation is declared, set but never used.

Hint:  Local arg1 arg2 is not used                    A local symbol is never used.

Note:  Private field arg1.arg2 is never used

Note:  Private field arg1.arg2 is assigned but never used

Note:  Private method arg1.arg2 never used

Error:  Set type expected                The variable or expression isn't of type set.  This happens in
       an in statement.

Warning:  Function result does not seem to be set                               You  can  get  this  warning  if  the
       compiler thinks that a function return value is not set.  This will not be displayed for
       assembler procedures, or procedures that contain assembler blocks.

Warning:  Type arg1 is not aligned correctly in current record for C                                         Arrays  with
       sizes not multiples of 4 will be wrongly aligned for C structures.

Error:  Unknown record field identifier arg1                          The field doesn't exist in the record def-
       inition.

Warning:  Local variable arg1 does not seem to be initialized

Warning:  Variable arg1 does not seem to be initialized                                 These messages are displayed
       if the compiler thinks that a variable will be used (i.e.  appears in the right-hand-side
       of an expression) when it wasn't initialized first (i.e.  appeared in the left-hand side of
       an assigment)

Error:  identifier idents no member arg1                        When using the extended syntax of new, you
       must specify the constructor method of the class you are trying to create.  The proce-
       dure you specified does not exist.

Found declaration:  arg1               You get this when you use the -vb switch.  In case an overloaded
       procedure is not found, then all candidate overloaded procedures are listed, with their
       parameter lists.

Error:  Data segment too large (max.  2GB)                            You get this when you declare an array
       whose size exceeds the 2GB limit.
C.6         Code  generator  messages


This section lists all messages that can be displayed if the code generator encounters an error
condition.


Error:  BREAK not allowed                    You're trying to use break outside a loop construction.

                                                                 79

____________________________________________________________________________C.6.___CODE_GENERATOR_MESSAGES_________________________*
 *___
Error:  CONTINUE not allowed                        You're trying to use continue outside a loop construc-
       tion.

Error:  Expression too complicated - FPU stack overflow                                   Your expression is too long
       for the compiler.  You should try dividing the construct over multiple assignments.

Error:  Illegal expression              This can occur under many circumstances.  Mostly when trying
       to evaluate constant expressions.

Error:  Invalid integer expression                   You made an expression which isn't an integer,  and
       the compiler expects the result to be an integer.

Error:  Illegal qualifier           One of the following is happening :

           o  You're trying to access a field of a variable that is not a record.

           o  You're indexing a variable that is not an array.

           o  You're dereferencing a variable that is not a pointer.

Error:  High range limit < low range limit                        You are declaring a subrange, and the lower
       limit is higher than the high limit of the range.

Error:  Illegal counter variable                 The type of a for loop variable must be an ordinal type.
       Loop variables cannot be reals or strings.

Error:  Can't determine which overloaded function to call                                   You're calling overloaded
       functions with a parameter that doesn't correspond to any of the declared function pa-
       rameter  lists.   e.g.   when  you  have  declared  a  function  with  parameters  word  and
       longint, and then you call it with a parameter which is of type integer.

Error:  Parameter list size exceeds 65535 bytes                            The I386 processor limits the param-
       eter list to 65535 bytes (the RET instruction causes this)

Error:  Illegal type conversion                 When doing a type-cast, you must take care that the sizes
       of the variable and the destination type are the same.

Conversion between ordinals and pointers is not portable across platforms                                              If you
       typecast a pointer to a longint, this code will not compile on a machine using 64bit for
       pointer storage.

Error:  File types must be var parameters                          You  cannot  specify  files  as  value  parame-
       ters, i.e.  they must always be declared var parameters.

Error:  The use of a far pointer isn't allowed there                            Free  Pascal  doesn't  support  far
       pointers, so you cannot take the address of an expression which has a far reference as
       a result.  The mem construct has a far reference as a result, so the following code will
       produce this error:


         var  p  :  pointer;
         ...
         p:=@mem[a000:000];
Error:  illegal call by reference parameters                        You  are  trying  to  pass  a  constant  or  an
       expression to a procedure that requires a var parameter.  Only variables can be passed
       as a var parameter.

Error:  EXPORT declared functions can't be called                                 No longer in use.

                                                                 80

____________________________________________________________________________C.6.___CODE_GENERATOR_MESSAGES_________________________*
 *___
Warning:  Possible illegal call of constructor or destructor (doesn't match to this context)
       No longer in use.

Note:  Inefficient code            You construction seems dubious to the compiler.

Warning:  unreachable code                  You specified a loop which will never be executed.  Example:


         while  false  do
            begin
            {..  code  ...}
            end;
Error:  procedure call with stackframe ESP/SP                               The  compiler  encountered  a  proce-
       dure  or  function  call  inside  a  procedure  that  uses  a  ESP/SP  stackframe.   Normally,
       when a call is done the procedure needs a EBP stackframe.

Error:  Abstract methods can't be called directly                             You cannot call an abstract method
       directy, instead you must call a overriding child method, because an abstract method
       isn't implemented.

Fatal:  Internal Error in getfloatreg(), allocation failure                             An  internal  error  occurred
       in the compiler; If you encounter such an error, please contact the developers and try
       to provide an exact description of the circumstances in which the error occurs.

Fatal:  Unknown float type                 The compiler cannot determine the kind of float that occurs
       in an expression.

Fatal:  SecondVecn() base defined twice                        An internal error occurred in the compiler; If
       you encounter such an error, please contact the developers and try to provide an exact
       description of the circumstances in which the error occurs.

Fatal:  Extended cg68k not supported                        The extended type is not supported on the m68k
       platform.

Fatal:  32-bit unsigned not supported in MC68000 mode                                     The  cardinal  is  not  sup-
       ported on the m68k platform.

Fatal:  Internal Error in secondinline()                     An  internal  error  occurred  in  the  compiler;  If
       you encounter such an error, please contact the developers and try to provide an exact
       description of the circumstances in which the error occurs.

Register arg1 weight arg2 arg3                    Debugging message.  Shown when the compiler consid-
       ers a variable for keeping in the registers.

Error:  Stack limit excedeed in local routine                         Your code requires a too big stack.  Some
       operating systems pose limits on the stack size.  You should use less variables or try ro
       put large variables on the heap.

Stack frame is omitted               Some procedure/functions do not need a complete stack-frame,
       so it is omitted.  This message will be displayed when the -vd switch is used.

Warning:  Range check for 64 bit integers is not supported on this target                                           64 bit range
       check is not yet implemented for 32 bit processors.

Error:  Object or class methods can't be inline.                           You cannot have inlined object meth-
       ods.

Error:  Procvar calls can't be inline.                    A procedure with a procedural variable call can-
       not be inlined.



                                                                 81

____________________________________________________________________________C.6.___CODE_GENERATOR_MESSAGES_________________________*
 *___
Error:  No code for inline procedure stored                          The compiler couldn't store code for the
       inline procedure.

Error:  Direct call of interrupt procedure arg1 is not possible                                  You  can  not  call  an
       interrupt procedure directly from FPC code

Error:  Element zero of an ansi/wide- or longstring can't be accessed, use (set)length instead
       You should use setlength to set the length of an ansi/wide/longstring and length to
       get the length of such kinf of string

Error:  Include and exclude not implemented in this case                                   include and exclude are
       only partially implemented for i386 processors and not at all for m68k processors.

Error:  Constructors or destructors can not be called inside a 'with' clause                                           Inside
       a With clause you cannot call a constructor or destructor for the object you have in
       the with clause.

Error:  Cannot call message handler method directly                                 A message method handler method
       can't be called directly if it contains an explicit self argument

Error:  Jump in or outside of an exception block                             It isn't allowed to jump in or out-
       side of an exception block like try..finally..end;:


         label  1;


         ...


         try
              if  not(final)  then
                 goto  1;     //  this  line  will  cause  an  error
         finally
            ...
         end;
         1:
         ...
Error:  Control flow statements aren't allowed in a finally block                                    It isn't allowed to
       use the control flow statements break, continue and exit inside a finally statement.
       The following example shows the problem:


         ...
            try
                 p;
            finally
                 ...
                 exit;    //  This  exit  ISN'T  allowed
            end;
         ...

       If the procedure p raises an exception the finally block is executed.  If the execution
       reaches the exit, it's unclear what to do:  exiting the procedure or searching for another
       exception handler

                                                                 82

_________________________________________________________C.7.___ERRORS_OF_ASSEMBLING/LINKING_STAGE_________________________________*
 *___
C.7         Errors  of  assembling/linking  stage


This  section  lists  errors  that  occur  when  the  compiler  is  processing  the  command  line  or
handling the configuration files.


Warning:  Source operating system redefined

Info:  Assembling (pipe) arg1

Error:  Can't create assember file:  arg1                      The mentioned file can't be create.  Check if
       you've permission to create this file

Error:  Can't create object file:  arg1                   The mentioned file can't be create.  Check if you've
       permission to create this file

Error:  Can't create archive file:  arg1                    The  mentioned  file  can't  be  create.   Check  if
       you've permission to create this file

Warning:  Assembler arg1 not found, switching to external assembling

Using assembler:  arg1

Warning:  Error while assembling exitcode arg1

Warning:  Can't call the assembler, error arg1 switching to external assembling



Info:  Assembling arg1

Info:  Assembling smartlink arg1

Warning:  Object arg1 not found, Linking may fail !

Warning:  Library arg1 not found, Linking may fail !

Warning:  Error while linking

Warning:  Can't call the linker, switching to external linking

Info:  Linking arg1

Warning:  Util arg1 not found, switching to external linking

Using util arg1

Error:  Creation of Executables not supported

Error:  Creation of Dynamic/Shared Libraries not supported

Info:  Closing script arg1

Warning:  resource compiler not found, switching to external mode

Info:  Compiling resource arg1



                                                                 83

__________________________________________________________________________________C.8.___UNIT_LOADING_MESSAGES.____________________*
 *___
C.8         Unit  loading  messages.


This section lists all messages that can occur when the compiler is loading a unit from disk
into memory.  Many of these mesages are informational messages.


Unitsearch:  arg1           When you use the -vt, the compiler tells you where it tries to find unit
       files.

PPU Loading arg1               When  the  -vt  switch  is  used,  the  compiler  tells  you  what  units  it
       loads.

PPU Name:  arg1              When you use the -vu flag, the unit name is shown.

PPU Flags:  arg1            When you use the -vu flag, the unit flags are shown.

PPU Crc:  arg1           When you use the -vu flag, the unit CRC check is shown.

PPU Time:  arg1             When you use the -vu flag, the time the unit was compiled is shown.

PPU File too short              The ppufile is too short, not all declarations are present.

PPU Invalid Header (no PPU at the begin)                               A  unit  file  contains  as  the  first  three
       bytes the ascii codes of  PPU

PPU Invalid Version arg1                  This  unit  file  was  compiled  with  a  different  version  of  the
       compiler, and cannot be read.

PPU is compiled for an other processor                          This unit file was compiled for a different pro-
       cessor type, and cannot be read

PPU is compiled for an other target                        This unit file was compiled for a different proces-
       sor type, and cannot be read

PPU Source:  arg1             When you use the -vu flag, the unit CRC check is shown.

Writing arg1         When you specify the -vu switch, the compiler will tell you where it writes
       the unit file.

Fatal:  Can't Write PPU-File                   An error occurred when writing the unit file.

Fatal:  Error reading PPU-File                   This  means  that  the  unit  file  was  corrupted,  and  con-
       tains invalid information.  Recompilation will be necessary.

Fatal:  unexpected end of PPU-File                       Unexpected end of file.

Fatal:  Invalid PPU-File entry:  arg1                    The  unit  the  compiler  is  trying  to  read  is  cor-
       rupted, or generated with a newer version of the compiler.

Fatal:  PPU Dbx count problem                      There is an inconsistency in the debugging information
       of the unit.

Error:  Illegal unit name:  arg1                 The name of the unit doesn't match the file name.

Fatal:  Too much units              Free Pascal has a limit of 1024 units in a program.  You can change
       this behavior by changing the maxunits constant in the files.pas file of the compiler,
       and recompiling the compiler.

Fatal:  Circular unit reference between arg1 and arg2                                Two units are using each other
       in the interface part.  This is only allowed in the implementation part.  At least one
       unit must contain the other one in the implementation section.
                                                                 84

__________________________________________________________________C.9.___COMMAND-LINE_HANDLING_ERRORS______________________________*
 *___
Fatal:  Can't compile unit arg1, no sources available                              A unit was found that needs to
       be recompiled, but no sources are available.

Fatal:  Can't find unit arg1               You tried to use a unit of which the PPU file isn't found by
       the compiler.  Check your config files for the unit pathes

Warning:  Unit arg1 was not found but arg2 exists

Fatal:  Unit arg1 searched but arg2 found                         Dos  truncation  of  8  letters  for  unit  PPU
       files may lead to problems when unit name is longer than 8 letters.

Warning:  Compiling the system unit requires the -Us switch                                      When recompiling the
       system unit (it needs special treatment), the -Us must be specified.

Fatal:  There were arg1 errors compiling module, stopping                                    When  the  compiler  en-
       counters a fatal error or too many errors in a module then it stops with this message.

Load from arg1 (arg2) unit arg3                     When you use the -vu flag, which unit is loaded from
       which unit is shown.

Recompiling arg1, checksum changed for arg2

Recompiling arg1, source found only                        When  you  use  the  -vu  flag,  these  messages  tell
       you why the current unit is recompiled.

Recompiling unit, static lib is older than ppufile                           When you use the -vu flag, the com-
       piler warns if the static library of the unit are older than the unit file itself.

Recompiling unit, shared lib is older than ppufile                             When  you  use  the  -vu  flag,  the
       compiler warns if the shared library of the unit are older than the unit file itself.

Recompiling unit, obj and asm are older than ppufile                                  When  you  use  the  -vu  flag,
       the compiler warns if the assembler or object file of the unit are older than the unit
       file itself.

Recompiling unit, obj is older than asm                         When you use the -vu flag, the compiler warns
       if the assembler file of the unit is older than the object file of the unit.

Parsing interface of arg1               When you use the -vu flag, the compiler warns that it starts
       parsing the interface part of the unit

Parsing implementation of arg1                     When you use the -vu flag, the compiler warns that it
       starts parsing the implementation part of the unit

Second load for unit arg1                When you use the -vu flag, the compiler warns that it starts
       recompiling a unit for the second time.  This can happend with interdepend units.

PPU Check file arg1 time arg2                     When you use the -vu flag, the compiler show the file-
       name and date and time of the file which a recompile depends on
C.9         Command-line  handling  errors


This  section  lists  errors  that  occur  when  the  compiler  is  processing  the  command  line  or
handling the configuration files.


Warning:  Only one source file supported                          You can specify only one source file on the
       command line.  The first one will be compiled, others will be ignored.  This may indicate
       that you forgot a '-' sign.



                                                                 85

__________________________________________________________________C.9.___COMMAND-LINE_HANDLING_ERRORS______________________________*
 *___
Warning:  DEF file can be created only for OS/2                               This  option  can  only  be  specified
       when you're compiling for OS/2

Error:  nested response files are not supported                           you  cannot  nest  response  files  with
       the @file command-line option.

Fatal:  No source file name in command line                           The compiler expects a source file name
       on the command line.

Note:  No option inside arg1 config file                      The  compiler  didn't  find  any  option  in  that
       config file.

Error:  Illegal parameter:  arg1                 You specified an unknown option.

Hint:  -?  writes help pages               When an unknown option is given, this message is diplayed.

Fatal:  Too many config files nested                    You can only nest up to 16 config files.

Fatal:  Unable to open file arg1                  The option file cannot be found.

Note:  Reading further options from arg1                          Displayed when you have notes turned on,
       and the compiler switches to another options file.

Warning:  Target is already set to:  arg1                      Displayed if more than one -T option is spec-
       ified.

Warning:  Shared libs not supported on DOS platform, reverting to static                                              If you
       specify -CD for the dos platform, this message is displayed.  The compiler supports only
       static libraries under dos

Fatal:  too many IF(N)DEFs                    the #IF(N)DEF statements in the options file are not bal-
       anced with the #ENDIF statements.

Fatal:  too many ENDIFs                  the #IF(N)DEF statements in the options file are not balanced
       with the #ENDIF statements.

Fatal:  open conditional at the end of the file                         the  #IF(N)DEF  statements  in  the  op-
       tions file are not balanced with the #ENDIF statements.

Warning:  Debug information generation is not supported by this executable                                                It is
       possible to have a compiler executable that doesn't support the generation of debugging
       info.  If you use such an executable with the -g switch, this warning will be displayed.

Hint:  Try recompiling with -dGDB                        It  is  possible  to  have  a  compiler  executable  that
       doesn't support the generation of debugging info.  If you use such an executable with
       the -g switch, this warning will be displayed.

Error:  You are using the obsolete switch arg1                            this warns you when you use a switch
       that is not needed/supported anymore.  It is recommended that you remove the switch
       to overcome problems in the future, when the switch meaning may change.

Error:  You are using the obsolete switch arg1, please use arg2                                     this warns you when
       you use a switch that is not supported anymore.  You must now use the second switch
       instead.  It is recommended that you change the switch to overcome problems in the
       future, when the switch meaning may change.

Note:  Switching assembler to default source writing assembler                                      this notifies you that
       the assembler has been changed because you used the -a switch which can't be used
       with a binary assembler writer.

                                                                 86

__________________________________________________________________________C.10.___ASSEMBLER_READER_ERRORS._________________________*
 *___
Warning:  Assembler output selected "arg1" is not compatible with "arg2"

Warning:  "arg1" assembler use forced                         The assembler output selected can not generate
       object files with the correct format.  Therefore, the default assembler for this target is
       used instead.
C.10           Assembler  reader  errors.


This section lists the errors that are generated by the inline assembler reader.  They are not
the messages of the assembler itself.
C.10.1         General  assembler  errors

Divide by zero in asm evaluator                     This fatal error is reported when a constant assembler
       expressions does a division by zero.

Evaluator stack overflow, Evaluator stack underflow                                These fatal errors are reported
       when  a  constant  assembler  expression  is  too  big  to  evaluate  by  the  constant  parser.
       Try reducing the number of terms.

Invalid numeric format in asm evaluator                          This fatal error is reported when a non-numeric
       value is detected by the constant parser.  Normally this error should never occur.

Invalid Operator in asm evaluator                      This  fatal  error  is  reported  when  a  mathematical
       operator is detected by the constant parser.  Normally this error should never occur.

Unknown error in asm evaluator                       This fatal error is reported when an internal error is
       detected by the constant parser.  Normally this error should never occur.

Invalid numeric value              This  warning  is  emitted  when  a  conversion  from  octal,binary  or
       hexadecimal to decimal is outside of the supported range.

Escape sequence ignored                 This error is emitted when a non ANSI C escape sequence is
       detected in a C string.

Asm syntax error - Prefix not found                        This occurs when trying to use a non-valid prefix
       instruction

Asm syntax error - Trying to add more than one prefix                                    This  occurs  when  you  try
       to add more than one prefix instruction

Asm syntax error - Opcode not found                          You  have  tried  to  use  an  unsupported  or  un-
       known opcode

Constant value out of bounds                    This  error  is  reported  when  the  constant  parser  deter-
       mines that the value you are using is out of bounds,  either with the opcode or with
       the constant declaration used.

Non-label pattern contains @                    This only applied to the m68k and Intel styled assembler,
       this is reported when you try to use a non-label identifier with a '@' prefix.

Internal error in Findtype()

Internal Error in ConcatOpcode()

Internal Errror converting binary

Internal Errror converting hexadecimal



                                                                 87

__________________________________________________________________________C.10.___ASSEMBLER_READER_ERRORS._________________________*
 *___
Internal Errror converting octal

Internal Error in BuildScaling()

Internal Error in BuildConstant()

internal error in BuildReference()

internal error in HandleExtend()

Internal error in ConcatLabeledInstr()                        These  errors  should  never  occur,  if  they  do
       then  you  have  found  a  new  bug  in  the  assembler  parsers.  Please  contact  one  of  the
       developers.

Opcode not in table, operands not checked                            This warning only occurs when compiling
       the  system  unit,  or  related  files.   No  checking  is  performed  on  the  operands  of  the
       opcodes.

@CODE and @DATA not supported                              This Turbo Pascal construct is not supported.

SEG and OFFSET not supported                          This Turbo Pascal construct is not supported.

Modulo not supported                 Modulo constant operation is not supported.

Floating point binary representation ignored

Floating point hexadecimal representation ignored

Floating point octal representation ignored                          These warnings occur when a floating point
       constant are declared in a base other then decimal.  No conversion can be done on these
       formats.  You should use a decimal representation instead.

Identifier supposed external                 This  warning  occurs  when  a  symbol  is  not  found  in  the
       symolb table, it is therefore considered external.

Functions with void return value can't return any value in asm code                                          Only routines
       with a return value can have a return value set.

Error in binary constant

Error in octal constant

Error in hexadecimal constant

Error in integer constant                These errors are reported when you tried using an invalid con-
       stant expression, or that the value is out of range.

Invalid labeled opcode

Asm syntax error - error in reference

Invalid Opcode

Invalid combination of opcode and operands

Invalid size in reference

Invalid middle sized operand

Invalid three operand opcode

Assembler syntax error
                                                                 88

__________________________________________________________________________C.10.___ASSEMBLER_READER_ERRORS._________________________*
 *___
Invalid operand type              You  tried  using  an  invalid  combination  of  opcode  and  operands,
       check the syntax and if you are sure it is correct, please contact one of the developers.

Unknown identifier             The identifier you are trying to access does not exist, or is not within
       the current scope.

Trying to define an index register more than once

Trying to define a segment register twice

Trying to define a base register twice                      You are trying to define an index/segment reg-
       ister more then once.

Invalid field specifier           The record or object field you are trying to access does not exist,
       or is incorrect.

Invalid scaling factor

Invalid scaling value

Scaling value only allowed with index                       Allowed scaling values are 1,2,4 or 8.

Cannot use SELF outside a method                          You  are  trying  to  access  the  SELF  identifier  for
       objects outside a method.

Invalid combination of prefix and opcode                          This opcode cannot be prefixed by this in-
       struction

Invalid combination of override and opcode                            This opcode cannot be overriden by this
       combination

Too many operands on line                   At most three operand instructions exist on the m68k, and
       i386, you are probably trying to use an invalid syntax for this opcode.

Duplicate local symbol               You are trying to redefine a local symbol, such as a local label.

Unknown label identifer

Undefined local symbol

local symbol not found inside asm statement                             This label does not seem to have been
       defined in the current scope

Assemble node syntax error

Not a directive or local symbol                   The assembler statement is invalid, or you are not using
       a recognized directive.
C.10.2         I386  specific  errors

repeat prefix and a segment override on <= i386 ...                              A problem with interrupts and a
       prefix instruction may occur and may cause false results on 386 and earlier computers.

Fwait can cause emulation problems with emu387                                  This warning is reported when us-
       ing the FWAIT instruction, it can cause emulation problems on systems which use the
       em387.dxe emulator.

You need GNU as version >= 2.81 to compile this MMX code                                            MMX assembler code
       can only be compiled using GAS v2.8.1 or later.

NEAR ignored



                                                                 89

__________________________________________________________________________C.10.___ASSEMBLER_READER_ERRORS._________________________*
 *___
FAR ignored          NEAR and FAR are ignored in the intel assemblers, but are still accepted for
       compatiblity with the 16-bit code model.

Invalid size for MOVSX/MOVZX

16-bit base in 32-bit segment

16-bit index in 32-bit segment                   16-bit addressing is not supported, you must use 32-bit
       addressing.

Constant reference not allowed                    It is not allowed to try to address a constant memory
       address in protected mode.

Segment overrides not supported                       Intel  style  (eg:  rep  ds  stosb)  segment  overrides  are
       not support by the assembler parser.

Expressions of the form [sreg:reg...                    are  currently  not  supported]  To  access  a  memory
       operand  in  a  different  segment,  you  should  use  the  sreg:[reg...]   snytax  instead  of
       [sreg:reg...]

Size suffix and destination register do not match                             In intel AT&T syntax, you are us-
       ing a register size which does not concord with the operand size specified.

Invalid assembler syntax.  No ref with brackets

 Trying to use a negative index register

 Local symbols not allowed as references

 Invalid operand in bracket expression

 Invalid symbol name:

 Invalid Reference syntax

 Invalid string as opcode operand:

 Null label references are not allowed

 Using a defined name as a local label

 Invalid constant symbol

 Invalid constant expression

 / at beginning of line not allowed

 NOR not supported

 Invalid floating point register name

 Invalid floating point constant:

 Asm syntax error - Should start with bracket

 Asm syntax error - register:

 Asm syntax error - in opcode operand

 Invalid String expression

 Constant expression out of bounds

 Invalid or missing opcode



                                                                 90

__________________________________________________________________________C.10.___ASSEMBLER_READER_ERRORS._________________________*
 *___
 Invalid real constant expression

 Parenthesis are not allowed

 Invalid Reference

 Cannot use  ___SELF outside a method

 Cannot use  ___OLDEBP outside a nested procedure

 Invalid segment override expression

 Strings not allowed as constants

 Switching sections is not allowed in an assembler block

 Invalid global definition

 Line separator expected

 Invalid local common definition

 Invalid global common definition

 assembler code not returned to text

 invalid opcode size

 Invalid character:  <

 Invalid character:  >

 Unsupported opcode

 Invalid suffix for intel assembler

 Extended not supported in this mode

 Comp not supported in this mode

 Invalid Operand:

 Override operator not supported
C.10.3         m68k  specific  errors.

Increment and Decrement mode not allowed together                                     You are trying to use dec/inc
       mode together.

Invalid Register list in movem/fmovem                          The  register  list  is  invalid,  normally  a  range
       of registers should be separated by - and individual registers should be separated by a
       slash.

Invalid Register list for opcode

68020+ mode required to assemble

                                                                 91


Appendix   D


Run   time   errors



The Free Pascal Run-time library generates the following errors at run-time 1 :


1 Invalid function number                 You tried to call a dos function which doesn't exist.

2 File not found           You can get this error when you tried to do an operation on a file which
       doesn't exist.

3 Path not found            You can get this error when you tried to do an operation on a file which
       doesn't exist, or when you try to change to, or remove a directory that doesn't exist,
       or try to make a subdirectory of a subdirectory that doesn't exist.

4 Too many open files               When  attempting  to  open  a  file  for  reading  or  writing,  you  can
       get this error when your program has too many open files.

5 File access denied            You don't have access to the specified file.

6 Invalid file handle           If this happens, the file variable you are using is trashed; it indicates
       that your memory is corrupted.

12 Invalid file access code               This  will  happen  if  you  do  a  reset  or  rewrite  of  a  file  when
       FileMode is invalid.

15 Invalid drive number                The number given to the Getdir function specifies a non-existent
       disk.

16 Cannot remove current directory                        You get this if you try to remove the current di-
       irectory.

17 Cannot rename across drives                      You cannot rename a file such that it would end up on
       another disk or partition.

100 Disk read error             dos only.  An error occurred when reading from disk.  Typically when
       you try to read past the end of a file.

101 Disk write error             dos only.  Reported when the disk is full, and you're trying to write
       to it.

102 File not assigned             This is reported by Reset, Rewrite, Append, Rename and Erase, if
       you call them with an unassigne function as a parameter.
___________________________________________________1
     The linux port will generate only a subset of these.


                                                             92

___________________________________________________________________________________________________________________________________*
 *___
103 File not open            Reported by the following functions :  Close , Read, Write, Seek, EOf,
       FilePos, FileSize, Flush, BlockRead, and BlockWrite if the file isn't open.

104 File not open for input                 Reported by Read, BlockRead, Eof, Eoln, SeekEof or SeekE-
       oln if the file isn't opened with Reset.

105 File not open for output                  Reported by write if a text file isn't opened with Rewrite.

106 Invalid numeric format                  Reported  when  a  non-numerice  value  is  read  from  a  text
       file, when a numeric value was expected.

150 Disk is write-protected                 (Critical error, dos only.)

151 Bad drive request struct length                       (Critical error, dos only.)

152 Drive not ready              (Critical error, dos only.)

154 CRC error in data                (Critical error, dos only.)

156 Disk seek error             (Critical error, dos only.)

157 Unknown media type                    (Critical error, dos only.)

158 Sector Not Found                (Critical error, dos only.)

159 Printer out of paper                (Critical error, dos only.)

160 Device write fault              (Critical error, dos only.)

161 Device read fault              (Critical error, dos only.)

162 Hardware failure              (Critical error, dos only.)

200 Division by zero             You are dividing a number by zero.

201 Range check error                If you compiled your program with range checking on, then you
       can get this error in the following cases:

          1.  An array was accessed with an index outside its declared range.

          2.  You're  trying  to  assign  a  value  to  a  variable  outside  its  range  (for  instance  a
              enumerated type).

202 Stack overflow error                The stack has grown beyond itss maximum size.  This error can
       easily occur if you have recursive functions.

203 Heap overflow error                The  heap  has  grown  beyond  its  boundaries,  ad  you  are  rying
       to get more memory.  Please note that Free Pascal provides a growing heap, i.e.  the
       heap  will  try  to  allocate  more  memory  if  needed.  However,  if  the  heap  has  reached
       the maximum size allowed by the operating system or hardware, then you will get this
       error.

204 Invalid pointer operation                  This you will get if you call dispose or Freemem with an
       invalid pointer (notably, Nil)

205 Floating point overflow                 You are trying to use or produce too large real numbers.

206 Floating point underflow                   You are trying to use or produce too small real numbers.

207 Invalid floating point operation                     Can occur if you try to calculate the square root
       or logarithm of a negative number.

                                                                 93

___________________________________________________________________________________________________________________________________*
 *___
210 Object not initialized               When compiled with range checking on, a program will report
       this error if you call a virtal method without having initialized the VMT.

211 Call to abstract method                   Your program tried to execute an abstract virtual method.
       Abstract methods should be overridden, and the overriding method should be called.

212 Stream registration error                   This occurs when an invalid type is registered in the ob-
       jects unit.

213 Collection index out of range                     You  are  trying  to  access  a  collection  item  with  an
       invalid index.  (objects unit)

214 Collection overflow error                  The collection has reached its maximal size, and you are
       trying to add another element.  (objects unit)

216 General Protection fault                  You are trying to access memory outside your appointed
       memory.

217 Unhandled exception occurred                        An exception occurred, and there was no exception
       handler present.  The sysutils unit installs a default exception handler which catches all
       excpetions and exits gracefully.

227 Assertion failed error                An assertion failed, and no AssertErrorProc procedural vari-
       able was installed.



                                                                 94


Appendix   E


The   Floating   Point   Coprocessor



emulator



In this appendix we note some caveats when using the floating point emulator on GO32V2
systems.  Under GO32V1 systems, all is as described in the installation section.

Q: I don't have an 80387.  How do I compile and run floating point programs under GO32V2?

Q: What shall I install on a target machine which lacks hardware floating-point support?

A : Programs which use floating point computations and could be run on machines without
an 80387 should be allowed to dynamically load the emu387.dxe file at run-time if needed.
To do this you must link the emu387 unit to your exectuable program, for example:


         Program  MyFloat;


         Uses  emu387;


         var
           r:  real;
         Begin
           r:=1.0;
           WriteLn(r);
         end.


Emu387 takes care of loading the dynamic emulation point library.

You should always add emulation when you distribute floating-point programs.

A few users reported that the emulation won't work for them unless they explicitly tell DJGPP
there is no x87 hardware, like this:


           set  387=N
           set  emu387=c:/djgpp/bin/emu387.dxe


There  is  an  alternative  FP  emulator  called  WMEMU.  It  mimics  a  real  coprocessor  more
closely.

WARNING: We strongly suggest that you use WMEMU as FPU emulator, since emu387.dxe
does not emulate all the instructions which are used by the Run-Time Libary such as FWAIT.

Q: I have an 80387 emulator installed in my AUTOEXEC.BAT, but DJGPP-compiled float-
ing point programs still doesn't work.  Why?



                                                             95

___________________________________________________________________________________________________________________________________*
 *___
A : DJGPP switches the CPU to protected mode, and the information needed to emulate the
80387 is different.  Not to mention that the exceptions never get to the real-mode handler.
You must use emulators which are designed for DJGPP. Apart of emu387 and WMEMU, the
only other emulator known to work with DJGPP is Q87 from QuickWare.  Q87 is shareware
and is available from the QuickWare Web site.

Q: I run DJGPP in an  os/2 DOS box, and I'm told that  os/2 will install its own emulator
library  if  the  CPU  has  no  FPU,  and  will  transparently  execute  FPU  instructions.  So  why
won't DJGPP run floating-point code under  os/2 on my machine?

A : os/2 installs an emulator for native os/2 images, but does not provide FPU emulation
for DOS sessions.



                                                                 96


Appendix   F


A   sample   gdb.ini   file



Here you have a sample gdb.ini file listing, which gives better results when using gdb.  Under
linux you should put this in a .gdbinit file in your home directory or the current directory..


set  print  demangle  off
set  gnutarget  auto
set  verbose  on
set  complaints  1000
dir  ./rtl/dosv2
set  language  c++
set  print  vtbl  on
set  print  object  on
set  print  sym  on
set  print  pretty  on
disp  /i  $eip


define  pst
set  $pos=&$arg0
set  $strlen  =  {byte}$pos
print  {char}&$arg0.st@($strlen+1)
end


document  pst
   Print  out  a  pascal  string
end



                                                             97
