
Free  Pascal  supplied  units  :

Reference  guide.

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

                                               Reference guide for standard Free Pascal units.

                                                                                                                       1.8

                                                                                                            July 2000


Micha"el Van Canneyt
Florian Kl"ampfl
______________________________________________________________________________________________________________________________



Contents
1   The CRT unit.                                                                                              25

    1.1    Types, Variables, Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    25

    1.2    Procedures and Functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    26

           1.2.1      AssignCrt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    26

           1.2.2      CursorBig  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    27

           1.2.3      ClrEol  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    27

           1.2.4      ClrScr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    28

           1.2.5      CursorOff  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    28

           1.2.6      CursorOn  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    28

           1.2.7      Delay   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    28

           1.2.8      DelLine   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    29

           1.2.9      GotoXY  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    29

           1.2.10     HighVideo .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    30

           1.2.11     InsLine   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    30

           1.2.12     KeyPressed  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    31

           1.2.13     LowVideo  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    31

           1.2.14     NormVideo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    32

           1.2.15     NoSound   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    32

           1.2.16     ReadKey   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    33

           1.2.17     Sound  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    33

           1.2.18     TextBackground   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *33

           1.2.19     TextColor  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    34

           1.2.20     TextMode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    34

           1.2.21     WhereX  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    35

           1.2.22     WhereY  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    35

           1.2.23     Window  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    35


2   The DOS unit.                                                                                              37

    2.1    Types, Variables, Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    37

           2.1.1      Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    37

           2.1.2      Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    38
                                                              1

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           2.1.3      Variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    39

    2.2    Function list by category .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    40

           2.2.1      File handling   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    40

           2.2.2      Directory and disk handling  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    40

           2.2.3      Process handling  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 41

           2.2.4      System information    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    41

    2.3    Functions and Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    41

           2.3.1      AddDisk .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    41

           2.3.2      DiskFree .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    42

           2.3.3      DiskSize  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    42

           2.3.4      DosExitCode   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   43

           2.3.5      DosVersion   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    43

           2.3.6      EnvCount  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    44

           2.3.7      EnvStr .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    44

           2.3.8      Exec  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    45

           2.3.9      FExpand   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    45

           2.3.10     FindClose  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    45

           2.3.11     FindFirst   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    46

           2.3.12     FindNext   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    47

           2.3.13     FSearch  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    47

           2.3.14     FSplit   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    47

           2.3.15     GetCBreak   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    48

           2.3.16     GetDate  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    48

           2.3.17     GetEnv   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    49

           2.3.18     GetFAttr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    49

           2.3.19     GetFTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    50

           2.3.20     GetIntVec  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    51

           2.3.21     GetLongName   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *51

           2.3.22     GetShortName   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 51

           2.3.23     GetTime    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    51

           2.3.24     GetVerify   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    52

           2.3.25     Intr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    52

           2.3.26     Keep  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    52

           2.3.27     MSDos    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    53

           2.3.28     PackTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    53

           2.3.29     SetCBreak    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    54

           2.3.30     SetDate   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    54

           2.3.31     SetFAttr .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    54

           2.3.32     SetFTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    55

           2.3.33     SetIntVec   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    55



                                                                 2

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           2.3.34     SetTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    55

           2.3.35     SetVerify   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    55

           2.3.36     SwapVectors   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   55

           2.3.37     UnPackTime   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  56


3   The DXELOAD unit                                                                                     57

    3.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    57

    3.2    Constants, types and variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    57

           3.2.1      Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    57

           3.2.2      Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    57

    3.3    Functions and Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    57

           3.3.1      dxe__ load   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    57


4   The EMU387 unit                                                                                         59

    4.1    Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    59

           4.1.1      npxsetup   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    59


5   The GETOPTS unit.                                                                                    60

    5.1    Types, Constants and variables :   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    60

           5.1.1      Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    60

           5.1.2      Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    60

           5.1.3      Variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    61

    5.2    Procedures and functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    61

           5.2.1      GetLongOpts  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  61

           5.2.2      Getopt .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    61


6   The GPM unit                                                                                              64

    6.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    64

    6.2    Constants, types and variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    64

           6.2.1      constants   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    64

           6.2.2      Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    65

           6.2.3      Variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    66

    6.3    Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    66

           6.3.1      Gpm__ AnyDouble    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    66

           6.3.2      Gpm__ AnySingle   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 66

           6.3.3      Gpm__ AnyTriple   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 67

           6.3.4      Gpm__ Close  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    67

           6.3.5      Gpm__ FitValues    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  67

           6.3.6      Gpm__ FitValuesM   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    67

           6.3.7      Gpm__ GetEvent    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 68

           6.3.8      Gpm__ GetLibVersion  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    69

                                                                 3

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           6.3.9      Gpm__ GetServerVersion   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    69

           6.3.10     Gpm__ GetSnapshot .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    69

           6.3.11     Gpm__ LowerRoi    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 70

           6.3.12     Gpm__ Open  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    70

           6.3.13     Gpm__ PopRoi  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   70

           6.3.14     Gpm__ PushRoi   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  70

           6.3.15     Gpm__ RaiseRoi  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  71

           6.3.16     Gpm__ Repeat  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   71

           6.3.17     Gpm__ StrictDouble  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *71

           6.3.18     Gpm__ StrictSingle   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 71

           6.3.19     Gpm__ StrictTriple   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 72


7   The GO32 unit                                                                                             73

    7.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    73

    7.2    Protected mode memory organization   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    73

           7.2.1      What is DPMI   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 73

           7.2.2      Selectors and descriptors .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    73

           7.2.3      FPC specialities   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  74

           7.2.4      dos memory access .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    74

           7.2.5      I/O port access  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   74

           7.2.6      Processor access   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  74

           7.2.7      Interrupt redirection  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *74

           7.2.8      Handling interrupts with DPMI .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    75

           7.2.9      Protected mode interrupts vs.  Real mode interrupts   .  .  .  .  .  .  .  .  .  .    75

           7.2.10     Creating own interrupt handlers   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    75

           7.2.11     Disabling interrupts   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *75

           7.2.12     Hardware interrupts   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    75

           7.2.13     Software interrupts  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 77

           7.2.14     Real mode callbacks   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    79

    7.3    Types, Variables and Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    80

           7.3.1      Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    80

           7.3.2      Predefined types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  81

           7.3.3      Variables.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    82

    7.4    Functions and Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    82

           7.4.1      allocate__ ldt__ descriptors  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 82

           7.4.2      allocate__ memory__ block  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    84

           7.4.3      copyfromdos    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    85

           7.4.4      copytodos  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    85

           7.4.5      create__ code__ segment__ alias__ descriptor   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    85

           7.4.6      disable  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    86
                                                                 4

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           7.4.7      dosmemfillchar   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   86

           7.4.8      dosmemfillword  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  87

           7.4.9      dosmemget   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    87

           7.4.10     dosmemmove   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  87

           7.4.11     dosmemput  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   88

           7.4.12     enable  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    88

           7.4.13     free__ ldt__ descriptor    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    88

           7.4.14     free__ memory__ block   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 89

           7.4.15     free__ rm__ callback .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    89

           7.4.16     get__ cs  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    89

           7.4.17     get__ descriptor__ access__ rights  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    90

           7.4.18     get__ ds  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    90

           7.4.19     get__ linear__ addr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    90

           7.4.20     get__ meminfo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    90

           7.4.21     get__ next__ selector__ increment__ value  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    91

           7.4.22     get__ page__ size   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    92

           7.4.23     get__ pm__ interrupt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   92

           7.4.24     get__ rm__ callback  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    92

           7.4.25     get__ rm__ interrupt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   95

           7.4.26     get__ run__ mode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    95

           7.4.27     get__ segment__ base__ address  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    96

           7.4.28     get__ segment__ limit  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   96

           7.4.29     get__ ss  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    97

           7.4.30     global__ dos__ alloc  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    97

           7.4.31     global__ dos__ free   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    98

           7.4.32     inportb   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    99

           7.4.33     inportl  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    99

           7.4.34     inportw   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    99

           7.4.35     lock__ code  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    99

           7.4.36     lock__ data  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  100

           7.4.37     lock__ linear__ region  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  100

           7.4.38     outportb .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  100

           7.4.39     outportl  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  101

           7.4.40     outportw   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  101

           7.4.41     realintr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  101

           7.4.42     seg__ fillchar   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  102

           7.4.43     seg__ fillword  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  103

           7.4.44     segment__ to__ descriptor   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  103

           7.4.45     seg__ move  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  103

           7.4.46     set__ descriptor__ access__ rights  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  104



                                                                 5

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           7.4.47     set__ pm__ interrupt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 104

           7.4.48     set__ rm__ interrupt    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  105

           7.4.49     set__ segment__ base__ address  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  105

           7.4.50     set__ segment__ limit  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 106

           7.4.51     tb__ size   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  106

           7.4.52     transfer__ buffer  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  106

           7.4.53     unlock__ code   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  106

           7.4.54     unlock__ data   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  107

           7.4.55     unlock__ linear__ region   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *07


8   The GRAPH unit.                                                                                      108

    8.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  108

           8.1.1      Requirements  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 108

           8.1.2      A word about mode selection  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  108

    8.2    Constants, Types and Variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  113

           8.2.1      Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  113

    8.3    Function list by category .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  113

           8.3.1      Initialization   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  113

           8.3.2      screen management .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  114

           8.3.3      Color management  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  114

           8.3.4      Drawing primitives  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  115

           8.3.5      Filled drawings  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 115

           8.3.6      Text and font handling    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116

    8.4    Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116

           8.4.1      Arc    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  116

           8.4.2      Bar    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  116

           8.4.3      Bar3D  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  116

           8.4.4      Circle   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  117

           8.4.5      ClearDevice  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  117

           8.4.6      ClearViewPort   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *117

           8.4.7      CloseGraph  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  117

           8.4.8      DetectGraph   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 117

           8.4.9      DrawPoly  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  118

           8.4.10     Ellipse  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  118

           8.4.11     FillEllipse  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  118

           8.4.12     FillPoly   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  118

           8.4.13     FloodFill   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  118

           8.4.14     GetArcCoords   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *19

           8.4.15     GetAspectRatio    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *19

           8.4.16     GetBkColor  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  119
                                                                 6

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           8.4.17     GetColor   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  119

           8.4.18     GetDefaultPalette   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  119

           8.4.19     GetDriverName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *19

           8.4.20     GetFillPattern   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 120

           8.4.21     GetFillSettings  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 120

           8.4.22     GetGraphMode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  120

           8.4.23     GetImage   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  120

           8.4.24     GetLineSettings    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *120

           8.4.25     GetMaxColor  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *120

           8.4.26     GetMaxMode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *21

           8.4.27     GetMaxX  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  121

           8.4.28     GetMaxY  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  121

           8.4.29     GetModeName   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  121

           8.4.30     GetModeRange  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  121

           8.4.31     GetPalette    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  121

           8.4.32     GetPaletteSize   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 122

           8.4.33     GetPixel .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  122

           8.4.34     GetTextSettings   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *22

           8.4.35     GetViewSettings   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *22

           8.4.36     GetX    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  122

           8.4.37     GetY    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  122

           8.4.38     GraphDefaults   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *123

           8.4.39     GraphErrorMsg .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  123

           8.4.40     GraphResult   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 123

           8.4.41     ImageSize  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  123

           8.4.42     InitGraph  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  124

           8.4.43     InstallUserDriver  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *124

           8.4.44     InstallUserFont  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 124

           8.4.45     Line   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  125

           8.4.46     LineRel   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  125

           8.4.47     LineTo .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  125

           8.4.48     MoveRel  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  125

           8.4.49     MoveTo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  125

           8.4.50     OutText  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  126

           8.4.51     OutTextXY  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 126

           8.4.52     PieSlice   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  126

           8.4.53     PutImage   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  126

           8.4.54     PutPixel .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  127

           8.4.55     Rectangle  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  127

           8.4.56     RegisterBGIDriver  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  127



                                                                 7

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           8.4.57     RegisterBGIFont  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  127

           8.4.58     RestoreCRTMode   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  127

           8.4.59     Sector  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  128

           8.4.60     SetActivePage   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *128

           8.4.61     SetAllPallette  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  128

           8.4.62     SetAspectRatio  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *128

           8.4.63     SetBkColor   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  128

           8.4.64     SetColor  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  129

           8.4.65     SetFillPattern .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  129

           8.4.66     SetFillStyle   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  129

           8.4.67     SetGraphBufSize  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  129

           8.4.68     SetGraphMode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  130

           8.4.69     SetLineStyle    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  130

           8.4.70     SetPalette  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  130

           8.4.71     SetRGBPalette  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *30

           8.4.72     SetTextJustify   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 131

           8.4.73     SetTextStyle   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  131

           8.4.74     SetUserCharSize   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *31

           8.4.75     SetViewPort   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 132

           8.4.76     SetVisualPage    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 132

           8.4.77     SetWriteMode    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *132

           8.4.78     TextHeight   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  132

           8.4.79     TextWidth   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  132

    8.5    Target specific issues  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *133

           8.5.1      dos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  133

           8.5.2      Windows 32-bit   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  133

           8.5.3      linux   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  133


9   The HEAPTRC unit.                                                                                  134

    9.1    Purpose   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  134

    9.2    Usage   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  134

    9.3    Constants, Types and variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  135

    9.4    Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  136

           9.4.1      DumpHeap   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 136

           9.4.2      MarkHeap  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  136

           9.4.3      SetExtraInfo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  137

           9.4.4      SetHeapTraceOutput .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  138


10  The IPC unit.                                                                                             139

    10.1   Types, Constants and variables :   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  139

           10.1.1     Variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  139



                                                                 8

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           10.1.2     Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  139

           10.1.3     Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  140

    10.2   Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  144

           10.2.1     ftok   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  144

           10.2.2     msgget .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  144

           10.2.3     msgsnd   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  144

           10.2.4     msgrcv .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  145

           10.2.5     msgctl  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  145

           10.2.6     semget  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  148

           10.2.7     semop  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  148

           10.2.8     semctl  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  149

           10.2.9     shmget    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  153

           10.2.10    shmat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  154

           10.2.11    shmdt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  154

           10.2.12    shmctl  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  154


11  The LINUX unit.                                                                                        157

    11.1   Type, Variable and Constant declarations   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  157

           11.1.1     Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  157

           11.1.2     Variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  160

           11.1.3     Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  161

    11.2   Function list by category .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  165

           11.2.1     File Input/Output routines   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  165

           11.2.2     General File handling routines   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  165

           11.2.3     Pipes, FIFOs and streams    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  166

           11.2.4     Directory handling routines  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  166

           11.2.5     Process handling  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *66

           11.2.6     Signals .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  167

           11.2.7     System information    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  167

           11.2.8     Terminal functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  168

           11.2.9     Port input/output   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  168

           11.2.10    Utility routines  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  169

    11.3   Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  169

           11.3.1     Access  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  169

           11.3.2     Alarm  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  170

           11.3.3     AssignPipe   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  171

           11.3.4     AssignStream  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 171

           11.3.5     BaseName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  173

           11.3.6     CFMakeRaw   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *73

           11.3.7     CFSetISpeed   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 174
                                                                 9

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           11.3.8     CFSetOSpeed  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *174

           11.3.9     Chown  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  174

           11.3.10    Chmod   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  175

           11.3.11    Clone   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  176

           11.3.12    CloseDir  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  177

           11.3.13    CreateShellArgV  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  177

           11.3.14    DirName   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  178

           11.3.15    Dup   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  179

           11.3.16    Dup2    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  179

           11.3.17    EpochToLocal    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *180

           11.3.18    Execl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  181

           11.3.19    Execle  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  181

           11.3.20    Execlp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  182

           11.3.21    Execv   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  183

           11.3.22    Execve .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  184

           11.3.23    Execvp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  185

           11.3.24    FD__ ZERO   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  185

           11.3.25    FD__ Clr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  186

           11.3.26    FD__ IsSet  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  186

           11.3.27    FD__ Set  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  186

           11.3.28    fdClose   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  186

           11.3.29    fdFlush   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  187

           11.3.30    fdOpen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  187

           11.3.31    fdRead .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  188

           11.3.32    fdSeek  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  189

           11.3.33    fdTruncate   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  189

           11.3.34    fdWrite   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  190

           11.3.35    FExpand   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  190

           11.3.36    FLock  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  190

           11.3.37    FNMatch   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  191

           11.3.38    FSearch  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  191

           11.3.39    FSplit   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  192

           11.3.40    FSStat .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  192

           11.3.41    FStat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  193

           11.3.42    Fcntl .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  194

           11.3.43    Fcntl .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  195

           11.3.44    Fork  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  195

           11.3.45    FRename   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  195

           11.3.46    GetDate  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  196

           11.3.47    GetDateTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *197



                                                                 10

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           11.3.48    GetDomainName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  197

           11.3.49    GetEGid    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  197

           11.3.50    GetEUid .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  198

           11.3.51    GetEnv   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  198

           11.3.52    GetEpochTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  199

           11.3.53    GetFS  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  199

           11.3.54    GetGid   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  200

           11.3.55    GetHostName .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *00

           11.3.56    GetLocalTimezone  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  201

           11.3.57    GetPid    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  201

           11.3.58    GetPPid .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  201

           11.3.59    GetPriority   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  202

           11.3.60    GetTime    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  202

           11.3.61    GetTimeOfDay  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  203

           11.3.62    GetTimeOfDay  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  203

           11.3.63    GetTimezoneFile  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  203

           11.3.64    GetUid   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  203

           11.3.65    Glob  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  204

           11.3.66    GlobFree   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  204

           11.3.67    IOCtl   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  205

           11.3.68    IOperm   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  205

           11.3.69    IsATTY  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  206

           11.3.70    S__ ISBLK  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  206

           11.3.71    S__ ISCHR  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  206

           11.3.72    S__ ISDIR   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  206

           11.3.73    S__ ISFIFO .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  206

           11.3.74    S__ ISLNK  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  207

           11.3.75    S__ ISREG  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  207

           11.3.76    S__ ISSOCK   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  207

           11.3.77    Kill    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  208

           11.3.78    LStat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  208

           11.3.79    Link  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  209

           11.3.80    LocalToEpoch    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *210

           11.3.81    MkFifo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  211

           11.3.82    MMap  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  211

           11.3.83    MUnMap   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  213

           11.3.84    Nice   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  213

           11.3.85    Octal    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

           11.3.86    OpenDir  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  214

           11.3.87    pause   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  215



                                                                 11

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           11.3.88    PClose  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  215

           11.3.89    POpen .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  216

           11.3.90    ReadDir  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  217

           11.3.91    ReadLink   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  217

           11.3.92    ReadPort   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  218

           11.3.93    ReadPortB   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  218

           11.3.94    ReadPortL   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  218

           11.3.95    ReadPortW  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 219

           11.3.96    ReadTimezoneFile   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  219

           11.3.97    SeekDir   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  219

           11.3.98    Select   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  220

           11.3.99    SelectText  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  221

           11.3.100   SetPriority   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221

           11.3.101   Shell  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  221

           11.3.102   SigAction   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

           11.3.103   SigPending   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  223

           11.3.104   SigProcMask   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 223

           11.3.105   SigRaise  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  224

           11.3.106   SigSuspend   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  224

           11.3.107   Signal   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  225

           11.3.108   StringToPPchar    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *25

           11.3.109   SymLink    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  226

           11.3.110   SysInfo   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  227

           11.3.111   TCDrain    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  228

           11.3.112   TCFlow  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  229

           11.3.113   TCFlush .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  229

           11.3.114   TCGetAttr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  229

           11.3.115   TCGetPGrp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *230

           11.3.116   TCSendBreak  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *230

           11.3.117   TCSetAttr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  230

           11.3.118   TCSetPGrp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 231

           11.3.119   TTYName    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 231

           11.3.120   TellDir .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  231

           11.3.121   Umask  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  232

           11.3.122   Uname .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  232

           11.3.123   UnLink   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  232

           11.3.124   Utime   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  233

           11.3.125   WaitPid  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233

           11.3.126   WritePort  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  234

           11.3.127   WritePortB  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  234



                                                                 12

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           11.3.128   WritePortL   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  235

           11.3.129   WritePortW .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 235


12  The MATH unit                                                                                          236

    12.1   Constants and types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  236

    12.2   Function list by category .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  237

           12.2.1     Min/max determination  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  237

           12.2.2     Angle conversion  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *37

           12.2.3     Trigoniometric functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  237

           12.2.4     Hyperbolic functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  238

           12.2.5     Exponential and logarithmic functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  238

           12.2.6     Number converting  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  238

           12.2.7     Statistical functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *38

           12.2.8     Geometrical functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  239

    12.3   Functions and Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  239

           12.3.1     arccos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  239

           12.3.2     arcosh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  239

           12.3.3     arcsin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  240

           12.3.4     arctan2   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  240

           12.3.5     arsinh   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  241

           12.3.6     artanh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  241

           12.3.7     ceil  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  242

           12.3.8     cosh   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  242

           12.3.9     cotan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  243

           12.3.10    cycletorad  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  243

           12.3.11    degtograd  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  244

           12.3.12    degtorad .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  244

           12.3.13    floor  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  245

           12.3.14    frexp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  245

           12.3.15    gradtodeg  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  246

           12.3.16    gradtorad  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  246

           12.3.17    hypot   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  247

           12.3.18    intpower  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  247

           12.3.19    ldexp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  248

           12.3.20    lnxp1   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  248

           12.3.21    log10 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  249

           12.3.22    log2   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  249

           12.3.23    logn   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  250

           12.3.24    max   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  250

           12.3.25    maxIntValue   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 251
                                                                 13

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           12.3.26    maxvalue   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  251

           12.3.27    mean    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  252

           12.3.28    meanandstddev  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *53

           12.3.29    min   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  254

           12.3.30    minIntValue .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  254

           12.3.31    minvalue    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  255

           12.3.32    momentskewkurtosis  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  256

           12.3.33    norm .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  256

           12.3.34    popnstddev  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  257

           12.3.35    popnvariance   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  258

           12.3.36    power   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  258

           12.3.37    radtocycle  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

           12.3.38    radtodeg .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

           12.3.39    radtograd  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  260

           12.3.40    randg   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  260

           12.3.41    sincos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  261

           12.3.42    sinh   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  262

           12.3.43    stddev  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  262

           12.3.44    sum   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  263

           12.3.45    sumofsquares   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  263

           12.3.46    sumsandsquares .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *64

           12.3.47    tan  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  265

           12.3.48    tanh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

           12.3.49    totalvariance   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  266

           12.3.50    variance  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  266


13  The MMX unit                                                                                           268

    13.1   Variables, Types and constants   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  268

    13.2   Functions and Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  269

           13.2.1     Emms  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  269


14  The MsMouse unit                                                                                      270

    14.1   Constants, types and variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  270

    14.2   Functions and procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  271

           14.2.1     GetLastButtonPress   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  271

           14.2.2     GetLastButtonRelease  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  272

           14.2.3     GetMouseState  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *72

           14.2.4     HideMouse   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  274

           14.2.5     InitMouse  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  274

           14.2.6     LPressed    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  275

           14.2.7     MPressed   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  275



                                                                 14

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           14.2.8     RPressed   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  275

           14.2.9     SetMouseAscii   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *275

           14.2.10    SetMouseHideWindow  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  276

           14.2.11    SetMousePos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 276

           14.2.12    SetMouseShape  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *77

           14.2.13    SetMouseSpeed  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *78

           14.2.14    SetMouseWindow    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  279

           14.2.15    SetMouseXRange  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  279

           14.2.16    SetMouseYRange  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  280

           14.2.17    ShowMouse  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 280


15  The Objects unit.                                                                                        281

    15.1   Constants  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  281

    15.2   Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  282

    15.3   Procedures and Functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  283

           15.3.1     NewStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  283

           15.3.2     DisposeStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  284

           15.3.3     Abstract .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  284

           15.3.4     RegisterObjects .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *284

           15.3.5     RegisterType  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 284

           15.3.6     LongMul    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  286

           15.3.7     LongDiv  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  286

    15.4   TRect   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  286

           15.4.1     TRect.Empty  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *287

           15.4.2     TRect.Equals  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 287

           15.4.3     TRect.Contains  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *288

           15.4.4     TRect.Copy  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  288

           15.4.5     TRect.Union   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 288

           15.4.6     TRect.Intersect  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 289

           15.4.7     TRect.Move  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  290

           15.4.8     TRect.Grow .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 290

           15.4.9     TRect.Assign  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 291

    15.5   TObject  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  291

           15.5.1     TObject.Init   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  291

           15.5.2     TObject.Free   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  292

           15.5.3     TObject.Done    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *292

    15.6   TStream  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  293

           15.6.1     TStream.Get   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 293

           15.6.2     TStream.StrRead  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  294

           15.6.3     TStream.GetPos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  295
                                                                 15

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           15.6.4     TStream.GetSize  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  295

           15.6.5     TStream.ReadStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  296

           15.6.6     TStream.Open   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *96

           15.6.7     TStream.Close   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *296

           15.6.8     TStream.Reset   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *297

           15.6.9     TStream.Flush   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *297

           15.6.10    TStream.Truncate   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  297

           15.6.11    TStream.Put   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 297

           15.6.12    TStream.StrWrite   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  298

           15.6.13    TStream.WriteStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  298

           15.6.14    TStream.Seek  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 298

           15.6.15    TStream.Error   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *298

           15.6.16    TStream.Read   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *99

           15.6.17    TStream.Write   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *299

           15.6.18    TStream.CopyFrom   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  299

    15.7   TDosStream .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  300

           15.7.1     TDosStream.Init   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *01

           15.7.2     TDosStream.Done   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  301

           15.7.3     TDosStream.Close   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  301

           15.7.4     TDosStream.Truncate   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  302

           15.7.5     TDosStream.Seek .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  302

           15.7.6     TDosStream.Open   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  303

           15.7.7     TDosStream.Read   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  304

           15.7.8     TDosStream.Write  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  304

    15.8   TBufStream  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  304

           15.8.1     TBufStream.Init   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *05

           15.8.2     TBufStream.Done   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  305

           15.8.3     TBufStream.Close   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  306

           15.8.4     TBufStream.Flush   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  306

           15.8.5     TBufStream.Truncate   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  307

           15.8.6     TBufStream.Seek  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  307

           15.8.7     TBufStream.Open   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  307

           15.8.8     TBufStream.Read   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  307

           15.8.9     TBufStream.Write   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  308

    15.9   TMemoryStream   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  308

           15.9.1     TMemoryStream.Init .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  308

           15.9.2     TMemoryStream.Done  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  309

           15.9.3     TMemoryStream.Truncate .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  309

           15.9.4     TMemoryStream.Read  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  309

           15.9.5     TMemoryStream.Write   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  310



                                                                 16

___________________________________________________________________________________________________________________CONTENTS________*
 *___
    15.10  TCollection   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  310

           15.10.1    TCollection.Init .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 311

           15.10.2    TCollection.Load  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *11

           15.10.3    TCollection.Done  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *12

           15.10.4    TCollection.At   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 312

           15.10.5    TCollection.IndexOf   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  313

           15.10.6    TCollection.GetItem  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  314

           15.10.7    TCollection.LastThat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  314

           15.10.8    TCollection.FirstThat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  315

           15.10.9    TCollection.Pack  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *15

           15.10.10   TCollection.FreeAll .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  316

           15.10.11   TCollection.DeleteAll   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  317

           15.10.12   TCollection.Free   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *318

           15.10.13   TCollection.Insert   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *18

           15.10.14   TCollection.Delete   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *19

           15.10.15   TCollection.AtFree  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  319

           15.10.16   TCollection.FreeItem .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  320

           15.10.17   TCollection.AtDelete .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  320

           15.10.18   TCollection.ForEach  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  321

           15.10.19   TCollection.SetLimit  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  322

           15.10.20   TCollection.Error .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *22

           15.10.21   TCollection.AtPut   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  322

           15.10.22   TCollection.AtInsert  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  323

           15.10.23   TCollection.Store  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *323

           15.10.24   TCollection.PutItem  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  324

    15.11  TSortedCollection   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *24

           15.11.1    TSortedCollection.Init  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  325

           15.11.2    TSortedCollection.Load   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  325

           15.11.3    TSortedCollection.KeyOf   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  325

           15.11.4    TSortedCollection.IndexOf   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  326

           15.11.5    TSortedCollection.Compare  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  326

           15.11.6    TSortedCollection.Search   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  327

           15.11.7    TSortedCollection.Insert  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  328

           15.11.8    TSortedCollection.Store  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  329

    15.12  TStringCollection  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 329

           15.12.1    TStringCollection.GetItem    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  329

           15.12.2    TStringCollection.Compare   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  330

           15.12.3    TStringCollection.FreeItem   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  330

           15.12.4    TStringCollection.PutItem    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  331

    15.13  TStrCollection   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  331



                                                                 17

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           15.13.1    TStrCollection.GetItem   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  331

           15.13.2    TStrCollection.Compare  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  331

           15.13.3    TStrCollection.FreeItem  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  332

           15.13.4    TStrCollection.PutItem   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  332

    15.14  TUnSortedStrCollection  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  333

           15.14.1    TUnSortedStrCollection.Insert   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  333

    15.15  TResourceCollection   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  334

           15.15.1    TResourceCollection.KeyOf  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  334

           15.15.2    TResourceCollection.GetItem  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  334

           15.15.3    TResourceCollection.FreeItem .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  335

           15.15.4    TResourceCollection.PutItem  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  335

    15.16  TResourceFile .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  335

           15.16.1    TResourceFile Fields  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  335

           15.16.2    TResourceFile.Init   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *36

           15.16.3    TResourceFile.Done   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  336

           15.16.4    TResourceFile.Count .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  336

           15.16.5    TResourceFile.KeyAt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  336

           15.16.6    TResourceFile.Get  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  336

           15.16.7    TResourceFile.SwitchTo  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  337

           15.16.8    TResourceFile.Flush  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  337

           15.16.9    TResourceFile.Delete .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  337

           15.16.10   TResourceFile.Put  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  337

    15.17  TStringList   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  337

           15.17.1    TStringList.Load  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *38

           15.17.2    TStringList.Done  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *38

           15.17.3    TStringList.Get .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *338

    15.18  TStrListMaker   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 339

           15.18.1    TStrListMaker.Init  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  339

           15.18.2    TStrListMaker.Done  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  339

           15.18.3    TStrListMaker.Put  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  339

           15.18.4    TStrListMaker.Store  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  340


16  The PORTS unit                                                                                         341

    16.1   Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  341

    16.2   Types,constants and variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  341

           16.2.1     Types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  341

           16.2.2     variables .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  342


17  The PRINTER unit.                                                                                   343

    17.1   Types, Constants and variables :   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  343

    17.2   Procedures and functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  343



                                                                 18

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           17.2.1     AssignLst  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  343


18  The SOCKETS unit.                                                                                   345

    18.1   Types, Constants and variables :   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  345

    18.2   Functions and Procedures   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  346

           18.2.1     Accept  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  346

           18.2.2     Accept  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  347

           18.2.3     Accept  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  348

           18.2.4     Accept  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  348

           18.2.5     Bind  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  348

           18.2.6     Bind  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  349

           18.2.7     Connect  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  349

           18.2.8     Connect  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350

           18.2.9     Connect  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350

           18.2.10    Connect  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350

           18.2.11    GetPeerName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *351

           18.2.12    GetSocketName .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  351

           18.2.13    GetSocketOptions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  352

           18.2.14    Listen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  352

           18.2.15    Recv  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  353

           18.2.16    Send  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  353

           18.2.17    SetSocketOptions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *54

           18.2.18    Shutdown  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  354

           18.2.19    Sock2File   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  354

           18.2.20    Sock2Text  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

           18.2.21    Socket  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  355

           18.2.22    SocketPair .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

           18.2.23    Str2UnixSockAddr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  355


19  The STRINGS unit.                                                                                    357

    19.1   Functions and procedures.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  357

           19.1.1     StrAlloc  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  357

           19.1.2     StrCat  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  357

           19.1.3     StrComp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  358

           19.1.4     StrCopy  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  358

           19.1.5     StrDispose    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  359

           19.1.6     StrECopy  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  359

           19.1.7     StrEnd    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  360

           19.1.8     StrIComp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  360

           19.1.9     StrLCat  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  361

           19.1.10    StrLComp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  361



                                                                 19

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           19.1.11    StrLCopy   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  362

           19.1.12    StrLen  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  362

           19.1.13    StrLIComp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  363

           19.1.14    StrLower   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  363

           19.1.15    StrMove  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  363

           19.1.16    StrNew   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  364

           19.1.17    StrPas  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  364

           19.1.18    StrPCopy  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  365

           19.1.19    StrPos  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  365

           19.1.20    StrRScan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  366

           19.1.21    StrScan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  366

           19.1.22    StrUpper   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  367


20  The SYSUTILS unit.                                                                                  368

    20.1   Constants and types   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  368

    20.2   Function list by category .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  371

           20.2.1     String functions .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 371

           20.2.2     Formatting strings   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *72

           20.2.3     File input/output routines .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  372

           20.2.4     File handling routines   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  373

           20.2.5     Date/time routines  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  373

    20.3   Miscellaneous conversion routines  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  374

    20.4   Date and time functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  375

           20.4.1     Date and time formatting characters  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  375

           20.4.2     TDateTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 376

           20.4.3     Date  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  376

           20.4.4     DateTimeToFileDate .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  376

           20.4.5     DateTimeToStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *77

           20.4.6     DateTimeToString  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  377

           20.4.7     DateTimeToSystemTime    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  378

           20.4.8     DateTimeToTimeStamp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  378

           20.4.9     DateToStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  379

           20.4.10    DayOfWeek  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 379

           20.4.11    DecodeDate  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  380

           20.4.12    DecodeTime    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 380

           20.4.13    EncodeDate  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  381

           20.4.14    EncodeTime    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 381

           20.4.15    FileDateToDateTime .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  382

           20.4.16    FormatDateTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  382

           20.4.17    IncMonth   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  383
                                                                 20

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           20.4.18    IsLeapYear   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  383

           20.4.19    MSecsToTimeStamp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  384

           20.4.20    Now  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  384

           20.4.21    StrToDate  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  385

           20.4.22    StrToDateTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *85

           20.4.23    StrToTime   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  386

           20.4.24    SystemTimeToDateTime    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  387

           20.4.25    Time .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  387

           20.4.26    TimeStampToDateTime  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  387

           20.4.27    TimeStampToMSecs  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  388

           20.4.28    TimeToStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  388

    20.5   Disk functions .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  389

           20.5.1     AddDisk (Linux only)   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  389

           20.5.2     CreateDir  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  389

           20.5.3     DiskFree .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  390

           20.5.4     DiskSize  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  390

           20.5.5     GetCurrentDir   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *391

           20.5.6     RemoveDir   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  391

           20.5.7     SetCurrentDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 391

    20.6   File handling functions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  392

           20.6.1     ChangeFileExt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *392

           20.6.2     DeleteFile  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  392

           20.6.3     DoDirSeparators   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *93

           20.6.4     ExpandFileName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  393

           20.6.5     ExpandUNCFileName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  394

           20.6.6     ExtractFileDir   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 394

           20.6.7     ExtractFileDrive   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *395

           20.6.8     ExtractFileExt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 395

           20.6.9     ExtractFileName  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  395

           20.6.10    ExtractFilePath   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *96

           20.6.11    ExtractRelativePath  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  396

           20.6.12    FileAge   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  396

           20.6.13    FileClose   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

           20.6.14    FileCreate  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

           20.6.15    FileExists  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  398

           20.6.16    FileGetAttr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  398

           20.6.17    FileGetDate .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  400

           20.6.18    FileOpen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  400

           20.6.19    FileRead    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  401

           20.6.20    FileSearch  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  401



                                                                 21

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           20.6.21    FileSeek  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  401

           20.6.22    FileSetAttr (Not on Linux)   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  402

           20.6.23    FileSetDate (Not on Linux)  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  402

           20.6.24    FileTruncate   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  403

           20.6.25    FileWrite   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  403

           20.6.26    FindClose  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  403

           20.6.27    FindFirst   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  403

           20.6.28    FindNext   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  404

           20.6.29    GetDirs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  404

           20.6.30    RenameFile  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  405

           20.6.31    SetDirSeparators  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *06

    20.7   PChar functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *406

           20.7.1     Introduction    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  406

           20.7.2     StrAlloc  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  407

           20.7.3     StrBufSize .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  407

           20.7.4     StrDispose    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  408

           20.7.5     StrPCopy  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  408

           20.7.6     StrPLCopy   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  408

           20.7.7     StrPas  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  408

    20.8   String handling functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  409

           20.8.1     AdjustLineBreaks    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  409

           20.8.2     AnsiCompareStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  409

           20.8.3     AnsiCompareText   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  410

           20.8.4     AnsiExtractQuotedStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  411

           20.8.5     AnsiLastChar  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 411

           20.8.6     AnsiLowerCase  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *12

           20.8.7     AnsiQuotedStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *412

           20.8.8     AnsiStrComp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *413

           20.8.9     AnsiStrIComp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *13

           20.8.10    AnsiStrLastChar  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  414

           20.8.11    AnsiStrLComp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *15

           20.8.12    AnsiStrLIComp  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *16

           20.8.13    AnsiStrLower  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 416

           20.8.14    AnsiStrUpper  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 417

           20.8.15    AnsiUpperCase  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *18

           20.8.16    AppendStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  418

           20.8.17    AssignStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  419

           20.8.18    BCDToInt .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  419

           20.8.19    CompareMem  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *20

           20.8.20    CompareStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  420



                                                                 22

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           20.8.21    CompareText  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *421

           20.8.22    DisposeStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  422

           20.8.23    FloatToStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  422

           20.8.24    FloatToStrF    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  423

           20.8.25    FloatToText    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  424

           20.8.26    FmtStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  425

           20.8.27    Format   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  425

           20.8.28    FormatBuf   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  431

           20.8.29    IntToHex   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  431

           20.8.30    IntToStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  432

           20.8.31    IsValidIdent  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  432

           20.8.32    LeftStr .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  433

           20.8.33    LoadStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  433

           20.8.34    LowerCase    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  433

           20.8.35    NewStr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  434

           20.8.36    QuotedStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  434

           20.8.37    RightStr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  435

           20.8.38    StrFmt   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  435

           20.8.39    StrLFmt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  435

           20.8.40    StrToInt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  436

           20.8.41    StrToIntDef  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  437

           20.8.42    Trim  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  437

           20.8.43    TrimLeft    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  438

           20.8.44    TrimRight  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  438

           20.8.45    UpperCase   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  439



                                                                 23

___________________________________________________________________________________________________________________CONTENTS________*
 *___
About  this  guide


This  document  describes  all  constants,  types,  variables,  functions  and  procedures  as  they
are declared in the units that come standard with Free Pascal.

Throughout this document, we will refer to functions, types and variables with typewriter
font.  Functions and procedures gave their own subsections, and for each function or proce-
dure we have the following topics:


Declaration        The exact declaration of the function.

Description        What does the procedure exactly do ?

Errors     What errors can occur.

See Also       Cross references to other related functions/commands.


The cross-references come in two flavors:


    o  References to other functions in this manual.  In the printed copy, a number will appear
       after this reference.  It refers to the page where this function is explained.  In the on-line
       help pages, this is a hyperlink, on which you can click to jump to the declaration.

    o  References to Unix manual pages.  (For Linux related things only) they are printed in
       typewriter font, and the number after it is the Unix manual section.


The chapters are ordered alphabetically.  The functions and procedures in most cases also,
but don't count on it.  Use the table of contents for quick lookup.



                                                                 24


Chapter   1


The   CRT   unit.



This chapter describes the CRT unit for Free Pascal, both under dos linux and Windows
32-bit.  The unit was first written for dos by Florian kl"ampfl.  The unit was ported to linux
by Mark May1 , and enhanced by Micha"el Van Canneyt and Peter Vreman.  It works on the
linux  console,  and  in  xterm  and  rxvt  windows  under  X-Windows.   The  functionality  for
both is the same, except that under linux the use of an early implementation (versions 0.9.1
an earlier of the compiler) the crt unit automatically cleared the screen at program startup.
This chapter is divided in two sections.


    o  The first section lists the pre-defined constants, types and variables.

    o  The second section describes the functions which appear in the interface part of the
       CRT unit.
1.1        Types,  Variables,  Constants


Color definitions :


   Black  =  0;
   Blue  =  1;
   Green  =  2;
   Cyan  =  3;
   Red  =  4;
   Magenta  =  5;
   Brown  =  6;
   LightGray  =  7;
   DarkGray  =  8;
   LightBlue  =  9;
   LightGreen  =  10;
   LightCyan  =  11;
   LightRed  =  12;
   LightMagenta  =  13;
   Yellow  =  14;
   White  =  15;
   Blink  =  128;


Miscellaneous_constants____________________________
    1Current e-mail address mmay@dnaco.net



                                                             25

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                    TextAttr:  Byte  =  $07;
                    TextChar:  Char  =  '  ';
                    CheckBreak:  Boolean  =  True;
                    CheckEOF:  Boolean  =  False;
                    CheckSnow:  Boolean  =  False;
                    DirectVideo:  Boolean  =  False;
                    LastMode:  Word  =  3;
                    WindMin:  Word  =  $0;
                    WindMax:  Word  =  $184f;
                    ScreenWidth  =  80;
                    ScreenHeight  =  25;


                 Some  variables  for  compatibility  with  Turbo  Pascal.   However,  they're  not  used  by  Free
                 Pascal.


                 var
                    checkbreak  :  boolean;
                    checkeof  :  boolean;
                    checksnow  :  boolean;


                 The following constants define screen modes on a dos system:


                 Const
                    bw40  =  0;
                    co40  =  1;
                    bw80  =  2;
                    co80  =  3;
                    mono  =  7;


                 The TextAttr variable controls the attributes with which characters are written to screen.


                 var  TextAttr  :  byte;


                 The DirectVideo variable controls the writing to the screen.  If it is True, the the cursor is
                 set via direct port access.  If  False, then the BIOS is used.  This is defined under dos only.


                 var  DirectVideo  :  Boolean;


                 The Lastmode variable tells you which mode was last selected for the screen.  It is defined
                 on dos only.


                 var  lastmode  :  Word;
                 1.2        Procedures  and  Functions



                 1.2.1       AssignCrt

Declaration:      Procedure  AssignCrt  (Var  F:  Text);

Description:      AssignCrt  Assigns  a  file  F  to  the  console.  Everything  written  to  the  file  F  goes  to  the
                 console  instead.   If  the  console  contains  a  window,  everything  is  written  to  the  window
                 instead.

       Errors:    None.



                                                                                  26

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
     See also:    Window (35)


                 Listing:  crtex/ex1.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e A s s i g n C r t f u n c t i o n.  }


                 v a r
                    F   :  Text   ;
                 b e g i n
                    A s s i g n C r t(F ) ;
                    R e w r i t e(F ) ;  {  Don   ' t  f o r g e t to    open    f o r  o u t p u t!  }
                    WriteLn     ( F , 'T h i s|_|i s|_|w r i t t e|n_|to|_|t h|e_|A s s i g n e|d_|F i'l)e;
                    C l o s e(F  ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.2       CursorBig

Declaration:      Procedure  CursorBig  ;

Description:      Makes the cursor a big rectangle.  Not implemented on linux.

       Errors:    None.

     See also:    CursorOn (28), CursorOff  (28)
                 1.2.3       ClrEol

Declaration:      Procedure  ClrEol  ;

Description:      ClrEol clears the current line, starting from the cursor position, to the end of the window.
                 The cursor doesn't move

       Errors:    None.

     See also:    DelLine (29), InsLine (30), ClrScr (28)


                 Listing:  crtex/ex9.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example9      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e C l r E o l  f u n c t i o n.  }


                 b e g i n
                    Write    ( 'T h i s |_|l i n|e_|w i l|l_|be|_|c l e a r e|d_|from|_|t h e',
                               ' |_|c u r s o|r_|p o s t i o|n_|u n t|i_l|t h|e_|r i g h|t_|o|f_|t h|e_|s c r e'e)n;
                    GotoXY     ( 2 7 ,WhereY    ) ;
                    ReadKey      ;
                    C l r E o l;
                    WriteLn      ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                  27

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                 1.2.4       ClrScr

Declaration:      Procedure  ClrScr  ;

Description:      ClrScr clears the current window (using the current colors), and sets the cursor in the top
                 left corner of the current window.

       Errors:    None.

     See also:    Window (35)


                 Listing:  crtex/ex8.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e C l r S c r  f u n c t i o n.  }


                 b e g i n
                    W r i t e l n(' P r e s s|_|any |_|key |_|to|_|c l e a|r_|t h|e_|s c r e e'n) ;
                    ReadKey      ;
                    C l r S c r;
                    W r i t e l n(' Have   |_|f u n|_|w i t|h_|t h|e_|c l e a r e|d_|s c r e'e)n;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.5       CursorOff

Declaration:      Procedure  CursorOff  ;

Description:      Switches the cursor off (i.e.  the cursor is no longer visible).  Not implemented on linux.

       Errors:    None.

     See also:    CursorOn (28), CursorBig (27)
                 1.2.6       CursorOn

Declaration:      Procedure  CursorOn  ;

Description:      Switches the cursor on.  Not implemented on linux.

       Errors:    None.

     See also:    CursorBig (27), CursorOff  (28)
                 1.2.7       Delay

Declaration:      Procedure  Delay  (DTime:    Word);

Description:      Delay  waits  a  specified  number  of  milliseconds.   The  number  of  specified  seconds  is  an
                 approximation, and may be off a lot, if system load is high.

       Errors:    None

     See also:    Sound (33), NoSound (32)


                 Listing:  crtex/ex15.pp



                                                                                  28

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example15      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e D e l a y  f u n c t i o n.  }
                 v a r
                    i   :  l o n g i n t;
                 b e g i n
                    WriteLn     ( ' C o u n t i n g|_|Down ') ;
                    f o r  i : = 1 0  downto      1  do
                      b e g i n
                         WriteLn      ( i) ;
                          D e l a y( 1 0 0 0 ) ;{ Wait     one    s e c o n d}
                      end  ;
                    WriteLn     ( 'BOOM    ! ! ! ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.8       DelLine

Declaration:      Procedure  DelLine  ;

Description:      DelLine removes the current line.  Lines following the current line are scrolled 1 line up, and
                 an empty line is inserted at the bottom of the current window.  The cursor doesn't move.

       Errors:    None.

     See also:    ClrEol (27), InsLine (30), ClrScr (28)


                 Listing:  crtex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e I n s L i n e f u n c t i o n.  }


                 b e g i n
                    C l r S c r;
                    WriteLn      ;
                    WriteLn     ( ' L i n e|_|1 ') ;
                    WriteLn     ( ' L i n e|_|2 ') ;
                    WriteLn     ( ' L i n e|_|2 ') ;
                    WriteLn     ( ' L i n e|_|3 ') ;
                    WriteLn      ;
                    WriteLn     ( ' Oops   , |_|L i n e|_|2i|_|s|_|l i s t|e_d|t w i c,e',
                                  ' |_|l e t''s |_|d e l e t|e_|t h|e_|l i n|e_|a|t_|t h|e_|c u r s o|r_|p o s t i'o)n;
                    GotoXY     ( 1 , 3 ) ;
                    ReadKey      ;
                    D e l L i n e;
                    GotoXY     ( 1 , 1 0 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.9       GotoXY

Declaration:      Procedure  GotoXY  (X:  Byte;  Y:  Byte);

Description:      Positions the cursor at (X,Y), X in horizontal, Y in vertical direction relative to the origin
                 of the current window.  The origin is located at (1,1), the upper-left corner of the window.



                                                                                  29

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
       Errors:    None.

     See also:    WhereX (35), WhereY (35), Window (35)


                 Listing:  crtex/ex6.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e GotoXY       f u n c t i o n.  }


                 b e g i n
                    C l r S c r;
                    GotoXY     ( 1 0 , 1 0 ) ;
                    Write    ( ' 1 0 , 1 0 ') ;
                    GotoXY     ( 7 0 , 2 0 ) ;
                    Write    ( ' 7 0 , 2 0 ') ;
                    GotoXY     ( 1 , 2 2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.10        HighVideo

Declaration:      Procedure  HighVideo  ;

Description:      HighVideo  switches  the  output  to  highlighted  text.  (It  sets  the  high  intensity  bit  of  the
                 video attribute)

       Errors:    None.

     See also:    TextColor (34), TextBackground (33), LowVideo (31), NormVideo (32)


                 Listing:  crtex/ex14.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example14      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e LowVideo      ,   H i g h V i d e o, NormVideo         f u n c t*
 * i o n.s }


                 b e g i n
                    LowVideo      ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|w i t|h_|LowVideo   ') ;
                    H i g h V i d e o;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|w i t|h_|H i g h V i d'e)o;
                    NormVideo       ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|w i t|h_|NormVideo   ' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.11        InsLine

Declaration:      Procedure  InsLine  ;

Description:      InsLine  inserts  an  empty  line  at  the  current  cursor  position.  Lines  following  the  current
                 line are scrolled 1 line down, causing the last line to disappear from the window.  The cursor
                 doesn't move.

       Errors:    None.



                                                                                  30

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
     See also:    ClrEol (27), DelLine (29), ClrScr (28)


                 Listing:  crtex/ex10.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e I n s L i n e f u n c t i o n.  }


                 b e g i n
                    C l r S c r;
                    WriteLn      ;
                    WriteLn     ( ' L i n e|_|1 ') ;
                    WriteLn     ( ' L i n e|_|3 ') ;
                    WriteLn      ;
                    WriteLn     ( ' Oops   , |_|f o r g o|t_|L i n|e_|2 ,l|_|e't's |_|i n s e r|t_|a t|_|t h|e_|c u r s o|r_|p o s *
 *t i'o)n;
                    GotoXY     ( 1 , 3 ) ;
                    ReadKey      ;
                    I n s L i n e;
                    Write    ( ' L i n e|_|2 ') ;
                    GotoXY     ( 1 , 1 0 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.12        KeyPressed

Declaration:      Function  KeyPressed  :    Boolean;

Description:      The Keypressed function scans the keyboard buffer and sees if a key has been pressed.  If
                 this is the case, True is returned.  If not, False is returned.  The Shift,  Alt,  Ctrl keys
                 are not reported.  The key is not removed from the buffer, and can hence still be read after
                 the KeyPressed function has been called.

       Errors:    None.

     See also:    ReadKey (33)


                 Listing:  crtex/ex2.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example2      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e K e y P r e s s e d f u n c t i o n.  }


                 b e g i n
                    WriteLn     ( ' W a i t i n g|_|u n t i|l_|a|_|key|_|i|s_|p r e s s e'd) ;
                    r e p e a t
                    u n t i l  KeyPressed       ;
                   {  The    key    i s  not    Read   ,
                      so   i t   s h o u l d a l s o be    o u t p u t t e da t  t h e  commandline        }
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.13        LowVideo

Declaration:      Procedure  LowVideo  ;

                                                                                  31

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
Description:      LowVideo switches the output to non-highlighted text.  (It clears the high intensity bit of
                 the video attribute)

       Errors:    None.

     See also:    TextColor (34), TextBackground (33), HighVideo (30), NormVideo (32)


                 For an example, see HighVideo (30)
                 1.2.14        NormVideo

Declaration:      Procedure  NormVideo  ;

Description:      NormVideo  switches  the  output  to  the  defaults,  read  at  startup.  (The  defaults  are  read
                 from the cursor position at startup)

       Errors:    None.

     See also:    TextColor (34), TextBackground (33), LowVideo (31), HighVideo (30)


                 For an example, see HighVideo (30)
                 1.2.15        NoSound

Declaration:      Procedure  NoSound  ;

Description:      Stops the speaker sound.  This is not supported in linux

       Errors:    None.

     See also:    Sound (33)


                 Listing:  crtex/ex16.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example16      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e Sound      and    NoSound       f u n c t i o n.  }


                 v a r
                    i   :  l o n g i n t;
                 b e g i n
                    WriteLn     ( ' You  |_|w i l l|_|h e a|r_|some|_|t o n e s|_|from |_|y o u|r_|s p e a k e'r) ;
                    w h i l e (  i<15000)       do
                      b e g i n
                          i n c( i, 5 0 0 ) ;
                         Sound    ( i ) ;
                          D e l a y( 1 0 0 ) ;
                      end  ;
                    WriteLn     ( ' Q u i e t|_|now ! ') ;
                    NoSound      ;  { Stop     n o i s e}
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                  32

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                 1.2.16        ReadKey

Declaration:      Function  ReadKey  :    Char;

Description:      The  ReadKey  function  reads  1  key  from  the  keyboard  buffer,  and  returns  this.   If  an
                 extended or function key has been pressed, then the zero ASCII code is returned.  You can
                 then read the scan code of the key with a second ReadKey call.  Remark.  Key mappings
                 under Linux can cause the wrong key to be reported by ReadKey, so caution is needed when
                 using ReadKey.

       Errors:    None.

     See also:    KeyPressed (31)


                 Listing:  crtex/ex3.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example3      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e ReadKey       f u n c t i o n.  }


                 v a r
                    ch   :   c h a r;
                 b e g i n
                    w r i t e l n(' P r e s s|_|L e f/tR i g h t, |_|Esc= Q u i t' ) ;
                    r e p e a t
                        ch :=  ReadKey     ;
                        case    ch    of
                          # 0  :  b e g i n
                                      ch := ReadKey      ;  { Read     ScanCode      }
                                      case    ch    of
                                       # 7 5  :   WriteLn     ( ' L e f t') ;
                                       # 7 7  :   WriteLn     ( ' R i g h t') ;
                                      end  ;
                                  end  ;
                        # 2 7  :  WriteLn     ( ' ESC  ' ) ;
                        end  ;
                    u n t i l  ch =#27     { Esc  }
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.17        Sound

Declaration:      Procedure  Sound  (hz  :    word);

Description:      Sounds the speaker at a frequency of  hz.  This is not supported in linux

       Errors:    None.

     See also:    NoSound (32)
                 1.2.18        TextBackground

Declaration:      Procedure  TextBackground  (CL:  Byte);

Description:      TextBackground  sets  the  background  color  to  CL.  CL  can  be  one  of  the  predefined  color
                 constants.

       Errors:    None.



                                                                                  33

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
     See also:    TextColor (34), HighVideo (30), LowVideo (31), NormVideo (32)


                 Listing:  crtex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example13      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e T e x t B a c k g r o u n df u n c t i o n.  }


                 b e g i n
                    T e x t C o l o r(White    ) ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|w i t|h_|t h|e_|d e f a u|l_t|b a c k g r o u|n_d|c o l'o)r;
                    T e x t B a c k g r o u n(dGreen   ) ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|w i t|h_|a|_|Green|_|b a c k g r o u n'd) ;
                    T e x t B a c k g r o u n(dBrown   ) ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|w i t|h_|a|_|Brown|_|b a c k g r o u n'd) ;
                    T e x t B a c k g r o u n(dB l a c k) ;
                    WriteLn     ( ' Back   |_|w i t h|_|a|_|b l a c|k_|b a c k g r o u'n)d;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.19        TextColor

Declaration:      Procedure  TextColor  (CL:  Byte);

Description:      TextColor sets the foreground color to CL. CL can be one of the predefined color constants.

       Errors:    None.

     See also:    TextBackground (33), HighVideo (30), LowVideo (31), NormVideo (32)


                 Listing:  crtex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example12      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e T e x t C o l o r f u n c t i o n.  }


                 b e g i n
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|t h|e_|d e f a u|l_t|c o l o'r) ;
                    T e x t C o l o r(Red  ) ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|Red') ;
                    T e x t C o l o r(White    ) ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|White ' ) ;
                    T e x t C o l o r(L i g h t B l u e) ;
                    WriteLn     ( ' T h i s|_|i s|_|w r i t t e|n_|i|n_|L i g h|t_|B l u'e) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.20        TextMode

Declaration:      procedure  TextMode(Mode:    Integer);

Description:      TextMode  sets  the  textmode  of  the  screen  (i.e.   the  number  of  lines  and  columns  of  the
                 screen).  The lower byte is use to set the VGA text mode.

                 This procedure is only implemented on dos.

       Errors:    None.

     See also:    Window (35)



                                                                                  34

                 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                 1.2.21        WhereX

Declaration:      Function  WhereX  :  Byte;

Description:      WhereX  returns  the  current  X-coordinate  of  the  cursor,  relative  to  the  current  window.
                 The origin is (1,1), in the upper-left corner of the window.

       Errors:    None.

     See also:    GotoXY (29), WhereY (35), Window (35)


                 Listing:  crtex/ex7.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example7      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e WhereX      and    WhereY       f u n c t i o n s.  }


                 b e g i n
                    W r i t e l n(' C u r s o r|_|p o s t i o:n|_|X=', WhereX    , ' |_|Y=' ,WhereY     ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.22        WhereY

Declaration:      Function  WhereY  :  Byte;

Description:      WhereY  returns  the  current  Y-coordinate  of  the  cursor,  relative  to  the  current  window.
                 The origin is (1,1), in the upper-left corner of the window.

       Errors:    None.

     See also:    GotoXY (29), WhereX (35), Window (35)


                 Listing:  crtex/ex7.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example7      ;
                 u s e s  C r t;


                 {  Program       to    d e m o n s t r a t et h e WhereX      and    WhereY       f u n c t i o n s.  }


                 b e g i n
                    W r i t e l n(' C u r s o r|_|p o s t i o:n|_|X=', WhereX    , ' |_|Y=' ,WhereY     ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 1.2.23        Window

Declaration:      Procedure  Window  (X1,  Y1,  X2,  Y2:    Byte);

Description:      Window  creates  a  window  on  the  screen,  to  which  output  will  be  sent.  (X1,Y1)  are  the
                 coordinates of the upper left corner of the window, (X2,Y2) are the coordinates of the bottom
                 right corner of the window.  These coordinates are relative to the entire screen, with the top
                 left corner equal to (1,1) Further coordinate operations, except for the next Window call,
                 are relative to the window's top left corner.

       Errors:    None.

     See also:    GotoXY (29), WhereX (35), WhereY (35), ClrScr (28)



                                                                                  35

 ___________________________________________________________________________1.2.___PROCEDURES_AND_FUNCTIONS________________________*
 *____
 Listing:  crtex/ex5.pp

________________________________________________________________________________________________________________________________
 Program       Example5      ;
 u s e s  C r t;


 {  Program       to    d e m o n s t r a t et h e Window       f u n c t i o n.  }


 b e g i n
    C l r S c r;
    WriteLn     ( ' C r e a t i n g|_|a|_|window  |_|from  |_|3 0 , 1 0t|_|o|_|5 0 , 2)0;'
    Window     ( 3 0 , 1 0 , 5 0 , 2 0 ) ;
    WriteLn     ( ' We  |_|a r|e_|now|_|w r i t i n|g_|i n|_|t h i|s_|s m a l|l_|window |_|we|_|j u s t|_|c r e a t e,d|_|we|_|'+
                  ' can  ' ' t|_|g e t|_|o u t s i d|e_|i|t_|when|_|w r i t i n|g_|l o n|g_|l i n e|s_|l i k|e_|t h i|s_|one') ;
    Write    ( ' P r e s s|_|any|_|key |_|to|_|c l e a r|_|t h|e_|window  ' ) ;
    ReadKey      ;
    C l r S c r;
    Write    ( 'The   |_|window   |_|i s|_|c l e a r e,d|_|p r e s|s_|any|_|key|_|to |_|r e s t o r|e_|to|_|f u l l s c r e'e)n;
    ReadKey      ;
 { F u l l S c r e e n  i s 8 0 x25  }
    Window     ( 1 , 1 , 8 0 , 2 5 ) ;
    C l r s c r;
    W r i t e l n(' Back   |_|i n|_|F u l|l_|S c r e e'n) ;
_end__._________________________________________________________________________________________________________________________
                                                                  36


Chapter   2


The   DOS   unit.



This chapter describes the DOS unit for Free pascal, both under dos, os/2, Windows 32-bit
and linux.  The unit was first written for dos by Florian kl"ampfl.  It was ported to linux
by Mark May1 , and enhanced by Micha"el Van Canneyt.

Under non-dos systems, some of the functionality is lost, as it is either impossible or mean-
ingless to implement it.  Other than that, the functionality for all operating systems is the
same.

This chapter is divided in three sections:


    o  The first section lists the pre-defined constants, types and variables.

    o  The second section gives an overview of all functions available, grouped by category.

    o  The third section describes the functions which appear in the interface part of the DOS
       unit.
2.1        Types,  Variables,  Constants



2.1.1       Constants

The DOS unit implements the following constants:


   {Bitmasks  for  CPU  Flags}
   fcarry  =        $0001;
   fparity  =       $0004;
   fauxiliary  =  $0010;
   fzero  =          $0040;
   fsign  =          $0080;
   foverflow    =  $0800;
   {Bitmasks  for  file  attribute}
   readonly  =     $01;
   hidden  =        $02;
   sysfile  =       $04;
   volumeid  =     $08;
   directory  =    $10;
   archive  =       $20;
   anyfile  =       $3F;
___________________________________________________1
     Current e-mail address mmay@dnaco.net



                                                             37

_________________________________________________________________________2.1.___TYPES,_VARIABLES,_CONSTANTS________________________*
 *___
   fmclosed  =     $D7B0;
   fminput  =       $D7B1;
   fmoutput  =     $D7B2;
   fminout  =       $D7B3;
2.1.2       Types

The following string types are defined for easy handling of filenames :


   ComStr    =  String[255];     {  For  command-lines  }
   PathStr  =  String[255];     {  For  full  path  for  file  names  }
   DirStr    =  String[255];     {  For  Directory  and  (DOS)  drive  string  }
   NameStr  =  String[255];     {  For  Name  of  file  }
   ExtStr    =  String[255];     {  For  Extension  of  file  }


   SearchRec  =  Packed  Record
      Fill  :  array[1..21]  of  byte;
      {  Fill  replaced  with  declarations  below,  for  Linux}
      Attr  :  Byte;  {attribute  of  found  file}
      Time  :  LongInt;  {last  modify  date  of  found  file}
      Size  :  LongInt;  {file  size  of  found  file}
      Reserved  :  Word;  {future  use}
      Name  :  String[255];  {name  of  found  file}
      SearchSpec:  String[255];  {search  pattern}
      NamePos:  Word;  {end  of  path,  start  of  name  position}
      End;


Under linux, the Fill array is replaced with the following:


      SearchNum:  LongInt;  {to  track  which  search  this  is}
      SearchPos:  LongInt;  {directory  position}
      DirPtr:  LongInt;  {directory  pointer  for  reading  directory}
      SearchType:  Byte;    {0=normal,  1=open  will  close}
      SearchAttr:  Byte;  {attribute  we  are  searching  for}
      Fill:  Array[1..07]  of  Byte;  {future  use}


This  is  because  the  searching  meachanism  on  Unix  systems  is  substantially  different  from
dos's, and the calls have to be mimicked.


const
   filerecnamelength  =  255;
type
   FileRec  =  Packed  Record
      Handle,
      Mode,
      RecSize     :  longint;
      _private    :  array[1..32]  of  byte;
      UserData    :  array[1..16]  of  byte;
      name          :  array[0..filerecnamelength]  of  char;
   End;


FileRec is used for internal representation of typed and untyped files.  Text files are handled
by the following types :



                                                                 38

_________________________________________________________________________2.1.___TYPES,_VARIABLES,_CONSTANTS________________________*
 *___
const
   TextRecNameLength  =  256;
   TextRecBufSize       =  256;
type
   TextBuf  =  array[0..TextRecBufSize-1]  of  char;
   TextRec  =  Packed  Record
      Handle,
      Mode,
      bufsize,
      _private,
      bufpos,
      bufend       :  longint;
      bufptr       :  ^textbuf;
      openfunc,
      inoutfunc,
      flushfunc,
      closefunc  :  pointer;
      UserData    :  array[1..16]  of  byte;
      name          :  array[0..textrecnamelength-1]  of  char;
      buffer       :  textbuf;
   End;


Remark  that  this  is  not  binary  compatible  with  the  Turbo  Pascal  definition  of  TextRec,
since the sizes of the different fields are different.


      Registers  =  record
         case  i  :  integer  of
             0  :  (ax,f1,bx,f2,cx,f3,dx,f4,bp,f5,si,
                     f51,di,f6,ds,f7,es,f8,flags,fs,gs  :  word);
             1  :  (al,ah,f9,f10,bl,bh,f11,f12,
                     cl,ch,f13,f14,dl,dh  :  byte);
             2  :  (eax,    ebx,    ecx,    edx,    ebp,    esi,    edi  :  longint);
             End;


The registers type is used in the MSDos call.


   DateTime  =  record
      Year:  Word;
      Month:  Word;
      Day:  Word;
      Hour:  Word;
      Min:  Word;
      Sec:  word;
      End;


The DateTime type is used in PackTime (53) and UnPackTime (56) for setting/reading file
times with GetFTime (50) and SetFTime (55).
2.1.3       Variables

      DosError  :  integer;


The DosError variable is used by the procedures in the dos unit to report errors.  It can
have the following values :



                                                                 39

___________________________________________________________________________2.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
                                             2     File not found.
                                             3     path not found.
                                             5     Access denied.
                                             6     Invalid handle.
                                             8     Not enough memory.
                                             10    Invalid environment.
                                             11    Invalid format.
                                             18    No more files.


Other values are possible, but are not documented.
2.2        Function  list  by  category


What follows is a listing of the available functions, grouped by category.  For each function
there is a reference to the page where you can find the function.
2.2.1       File  handling

Routines to handle files on disk.


Name_______________________________________________Description_________________________________________________Page___________

  FExpand                          Expand filename to full path                                               45

  FindClose                        Close finfirst/findnext session                                               45

  FindFirst                        Start find of file                                                                 46

  FindNext                         Find next file                                                                     47

  FSearch                          Search for file in a path                                                       47

  FSplit                           Split filename in parts                                                         47

  GetFAttr                         Return file attributes                                                          49

  GetFTime                         Return file time                                                                 50

  GetLongName                      Convert short filename to long filename                                 51

  GetShortName                     Convert long filename to short filename                                 51

  SetFAttr                         Set file attributes                                                               54

  SetFTime                         Set file time                                                                       55
2.2.2       Directory  and  disk  handling

Routines to handle disk information.


Name_______________________________________________Description_________________________________________________Page___________

  AddDisk                          Add disk to list of disks                                                      41

  DiskFree                         Return size of free disk space                                               42

  DiskSize                         Return total disk size                                                         42


                                                                 40

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 2.2.3       Process  handling

                 Functions to handle process information and starting new processes.


                 Name_______________________________________________Description_________________________________________________Pag*
 *e___________

                   DosExitCode                      Exit code of last executed program                                       43

                   EnvCount                         Return number of environment variables                               44

                   EnvStr                           Return environment string pair                                            44

                   Exec                             Execute program                                                                *
 *45

                   GetEnv                           Return specified environment string                                      49
                 2.2.4       System  information

                 Functions for retrieving and setting general system information such as date and time.


                 Name_______________________________________________Description_________________________________________________Pag*
 *e___________

                   DosVersion                       Get OS version                                                                 *
 * 43

                   GetCBreak                        Get setting of control-break handling flag                              48

                   GetDate                          Get system date                                                                *
 * 48

                   GetIntVec                        Get interrupt vector status                                                  51

                   GetTime                          Get system time                                                                *
 *51

                   GetVerify                        Get verify flag                                                                *
 *   52

                   Intr                             Execute an interrupt                                                          52

                   Keep                             Keep process in memory and exit                                         52

                   MSDos                            Execute MS-dos function call                                               53

                   PackTime                         Pack time for file time                                                        *
 *53

                   SetCBreak                        Set control-break handling flag                                             54

                   SetDate                          Set system date                                                                *
 * 54

                   SetIntVec                        Set interrupt vectors                                                          *
 * 55

                   SetTime                          Set system time                                                                *
 * 55

                   SetVerify                        Set verify flag                                                                *
 *    55

                   SwapVectors                      Swap interrupt vectors                                                        55

                   UnPackTime                       Unpack file time                                                               *
 * 56
                 2.3        Functions  and  Procedures



                 2.3.1       AddDisk

Declaration:      Procedure  AddDisk  (Const  S  :  String);

Description:      AddDisk adds a filename S to the internal list of disks.  It is implemented for linux only.
                 This list is used to determine which disks to use in the DiskFree (42) and DiskSize (42) calls.
                 The DiskFree (42) and DiskSize (42) functions need a file on the specified drive, since this is
                 required for the statfs system call.  The names are added sequentially.  The dos initialization
                 code presets the first three disks to:



                                                                                  41

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                      o'.'  for the current drive,

                      o'/fd0/.'  for the first floppy-drive.

                      o'/fd1/.'  for the second floppy-drive.

                      o'/' for the first hard disk.

                 The first call to AddDisk will therefore add a name for the second harddisk, The second call
                 for the third drive, and so on until 23 drives have been added (corresponding to drives 'D:'
                 to 'Z:')

       Errors:    None

     See also:    DiskFree (42), DiskSize (42)
                 2.3.2       DiskFree

Declaration:      Function  DiskFree  (Drive:    byte)  :    Int64;

Description:      DiskFree returns the number of free bytes on a disk.  The parameter Drive indicates which
                 disk should be checked.  This parameter is 1 for floppy a:, 2 for floppy b:, etc.  A value of
                 0 returns the free space on the current drive.  Typically, the free space is the size of a disk
                 block, multiplied by the number of free blocks on the disk.  For linux only:
                 The diskfree and disksize functions need a file on the specified drive, since this is required
                 for the statfs system call.  These filenames are set in the initialization of the dos unit, and
                 have been preset to :

                      o'.'  for the current drive,

                      o'/fd0/.'  for the first floppy-drive.

                      o'/fd1/.'  for the second floppy-drive.

                      o'/' for the first hard disk.

                 There is room for 1-26 drives.  You can add a drive with the AddDisk (41) procedure.  These
                 settings can be coded in dos.pp, in the initialization part.

       Errors:    -1 when a failure occurs, or an invalid drivenr is given.

     See also:    DiskSize (42), AddDisk (41)


                 Listing:  dosex/ex6.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e D i s k S i z e and    D i s k F r e e f u n c t i o n.  }


                 b e g i n
                    WriteLn     ( ' T h i s|_|p a r t i t i o|n_|s i z|e_|has|_|',D i s k S i z(e0 ) ,' |_|b y t e's) ;
                    WriteLn     ( ' C u r r e n t l y|_|',D i s k F r e(e0 ) ,' |_|b y t e|s_|a r|e_|f r e'e) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.3       DiskSize

Declaration:      Function  DiskSize  (Drive:    byte)  :    Int64;


                                                                                  42

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      DiskSize returns the total size (in bytes) of a disk.  The parameter Drive indicates which
                 disk should be checked.  This parameter is 1 for floppy a:, 2 for floppy b:, etc.  A value of 0
                 returns the size of the current drive.  For linux only:
                 The diskfree and disksize functions need a file on the specified drive, since this is required
                 for the statfs system call.  These filenames are set in the initialization of the dos unit, and
                 have been preset to :

                      o'.'  for the current drive,

                      o'/fd0/.'  for the first floppy-drive.

                      o'/fd1/.'  for the second floppy-drive.

                      o'/' for the first hard disk.

                 There is room for 1-26 drives.  You can add a drive with the AddDisk (41) procedure.  These
                 settings can be coded in dos.pp, in the initialization part.

       Errors:    -1 when a failure occurs, or an invalid drive number is given.

     See also:    DiskFree (42), AddDisk (41)


                 For an example, see DiskFree (42).
                 2.3.4       DosExitCode

Declaration:      Function  DosExitCode  :    Word;

Description:      DosExitCode contains (in the low byte) the exit-code of a program executed with the Exec
                 call.

       Errors:    None.

     See also:    Exec (45)


                 Listing:  dosex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example5      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e Exec     and    D o s E x i t C o d ef u n c t i o n.  }


                 b e g i n
                 {$IFDEF       LINUX   }
                    WriteLn     ( ' E x e c u t i n g|_|/b i/nl s|_|-l a ') ;
                    Exec   ( ' / b i n/ l s' ,'-  l a' ) ;
                 {$ELSE    }
                    WriteLn     ( ' E x e c u t i n g|_|D i'r) ;
                    Exec   ( GetEnv    ( ' COMSPEC     ' ) ,' / C |_|d i r') ;
                 {$ENDIF     }
                    WriteLn     ( ' Program     |_|r e t u r n e|d_|w i t|h_|E x i t C o d|e_|',D o s E x i t C o)d;e
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.5       DosVersion

Declaration:      Function  DosVersion  :    Word;

Description:      DosVersion  returns  the  dos  version  number.   On  linux  systems,  it  returns  the  Linux
                 version (The first 2 numbers, e.g Linux version 2.1.76 will give you DosVersion 2.1)



                                                                                  43

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    None.

     See also:


                 Listing:  dosex/ex1.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e D o s V e r s i o n f u n c t i o n.  }


                 v a r
                    OS            :   s t r i n g[ 3 2 ] ;
                    V e r s i o n :   word   ;
                 b e g i n
                 {$IFDEF       LINUX   }
                    OS  := ' L i n u x';
                 {$ENDIF     }
                 {$IFDEF      DOS   }
                    OS  := ' Dos  ' ;
                 {$ENDIF     }
                    V e r s i o n:= D o s V e r s i o;n
                    WriteLn     ( ' C u r r e n t|_|',OS , ' |_|v e r s i o|n_|i|s_|',Lo( V e r s i o n) ,' . ', Hi ( V e r s i o n*
 *) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.6       EnvCount

Declaration:      Function  EnvCount  :    longint;

Description:      EnvCount returns the number of environment variables.

       Errors:    None.

     See also:    EnvStr (44), Dos:GetEnv (49)
                 2.3.7       EnvStr

Declaration:      Function  EnvStr  (Index:    integer)  :    string;

Description:      EnvStr returns the Index-th Name=Value pair from the list of environment variables.  The
                 index of the first pair is zero.

       Errors:    The length is limited to 255 characters.  This may cause problems under linux.  The linux
                 unit solves this problem.

     See also:    EnvCount (44), Dos:GetEnv (49)


                 Listing:  dosex/ex13.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example13      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e EnvCount        and    E n v S t r f u n c t i o n.  }


                 v a r
                    i   :  L o n g i n t;
                                                                                  44

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 b e g i n
                    WriteLn     ( ' C u r r e n t|_|E n v i r o n m e|n_t|i:s') ;
                    f o r  i :=1  to   EnvCount        do
                      WriteLn     ( E n v S t r(i ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.8       Exec

Declaration:      Procedure  Exec  (const  Path:    pathstr;  const  ComLine:    comstr);

Description:      Exec executes the program in Path, with the options given by ComLine.  After the program
                 has terminated, the procedure returns.  The Exit value of the program can be consulted with
                 the DosExitCode function.

       Errors:    Errors are reported in DosError.

     See also:    DosExitCode (43)


                 For an example, see DosExitCode (43)
                 2.3.9       FExpand

Declaration:      Function  FExpand  (const  path:    pathstr)  :    pathstr;

Description:      FExpand takes its argument and expands it to a complete filename, i.e.  a filename starting
                 from the root directory of the current drive,  prepended with the drive-letter (under dos).
                 The resulting name is converted to uppercase on dos systems.  Under linux,  the name is
                 left as it is.  (filenames are case sensitive under Unix)

       Errors:    FSplit (47)

     See also:   __________________________________________________________________________________________________________________*
 *______________
                 Program       Example5      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e Exec     and    D o s E x i t C o d ef u n c t i o n.  }


                 b e g i n
                 {$IFDEF       LINUX   }
                    WriteLn     ( ' E x e c u t i n g|_|/b i/nl s|_|-l a ') ;
                    Exec   ( ' / b i n/ l s' ,'-  l a' ) ;
                 {$ELSE    }
                    WriteLn     ( ' E x e c u t i n g|_|D i'r) ;
                    Exec   ( GetEnv    ( ' COMSPEC     ' ) ,' / C |_|d i r') ;
                 {$ENDIF     }
                    WriteLn     ( ' Program     |_|r e t u r n e|d_|w i t|h_|E x i t C o d|e_|',D o s E x i t C o)d;e
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.10        FindClose

Declaration:      Procedure  FindClose  (Var  F:  SearchRec);

Description:      linux, Windows 32-bit and os/2 wonly FindClose frees any resources associated with
                 the search record F.


                                                                                  45

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Under linux, Windows 32-bit and os/2 the findfirst/findnext calls have to be mim-
                 icked.  This call is needed to free any internal resources allocated by the FindFirst (403) or
                 FindNext (404) calls.

                 E.g.  on linux, an internal table of file descriptors is kept.  When using different searchrecs
                 at the same time, the system may run out of file descriptors for directories.

                 The linux implementation of the dos unit therefore keeps a table of open directories, and
                 when  the  table  is  full,  closes  one  of  the  directories,  and  reopens  another.   This  system  is
                 adequate  but  slow  if  you  use  a  lot  of  searchrecs.  So,  to  speed  up  the  findfirst/findnext
                 system, the FindClose call was implemented.  When you don't need a searchrec any more,
                 you can tell this to the dos unit by issuing a FindClose call.  The directory which is kept
                 open for this searchrec is then closed, and the table slot freed.

                 It is recommended to use the linux call Glob when looking for files on linux.

       Errors:    None.

     See also:    Glob (204).
                 2.3.11        FindFirst

Declaration:      Procedure  FindFirst  (const  Path:    pathstr;  Attr:    word;  var  F:  SearchRec);

Description:      FindFirst searches the file specified in Path, checks the atrributes specified in Attr.  It re-
                 turns a SearchRec record for further searching in F. Path can contain the wildcard characters
                 ?  (matches any single character) and * (matches 0 ore more arbitrary characters).  In this
                 case FindFirst will return the first file which matches the specified criteria.  If  DosError is
                 different from zero, no file(s) matching the criteria was(were) found.

                 On  os/2,  you  cannot  issue  two  different  FindFirst  calls.   That  is,  you  must  close  any
                 previous  search  operation  with  FindClose  (45)  before  starting  a  new  one.  Failure  to  do  so
                 will end in a Run-Time Error 6 (Invalid file handle)

                 Also, on os/2, the boolean variable FileNameCaseSensitive indicates whether searches are
                 conducted case-sensitive or not.  By default, searches are not case sensitive.  If the varieble
                 is set to True, searches on os/2 are case sensistive.

       Errors:    Errors are reported in DosError.

     See also:    FindNext (47), FindClose (45)


                 Listing:  dosex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example7      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e  F i n d F i r s tand    F i n d N e x t f u n c t i o n.  }


                 v a r
                    D i r  :   S e a r c h R e;c
                 b e g i n
                    F i n d F i r s t(' * . * ',$20  , D i r) ;
                    WriteLn     ( ' F i l e N a m e'+Space    ( 3 2 ) ,' F i l e S i z e': 9 ) ;
                    w h i l e (  D o s E r r o=r0)   do
                      b e g i n
                          W r i t e l n(D i r.Name   + Space    (40-   Length    ( D i r. Name   ) ) ,D i r. S i z e: 9 ) ;
                         FindNext      ( D i r ) ;
                      end  ;
                    F i n d C l o s e(D i r) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                  46

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 2.3.12        FindNext

Declaration:      Procedure  FindNext  (var  f:    searchRec);

Description:      FindNext takes as an argument a SearchRec from a previous FindNext call, or a FindFirst
                 call, and tries to find another file which matches the criteria, specified in the FindFirst call.
                 If  DosError is different from zero, no more files matching the criteria were found.

       Errors:    DosError is used to report errors.

     See also:    FindFirst (46), FindClose (45)


                 For an example, see FindFirst (46).
                 2.3.13        FSearch

Declaration:      Function  FSearch  (Path:    pathstr;  DirList:    string)  :    pathstr;

Description:      FSearch  searches  the  file  Path  in  all  directories  listed  in  DirList.  The  full  name  of  the
                 found  file  is  returned.  DirList  must  be  a  list  of  directories,  separated  by  semi-colons  (or
                 colons under linux).  When no file is found, an empty string is returned.

       Errors:    None.

     See also:    FExpand (45)


                 Listing:  dosex/ex10.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e F S e a r c h f u n c t i o n.  }


                 v a r
                    s   :  s t r i n g;
                 b e g i n
                    s :=  F S e a r c h(ParamStr      ( 1 ) ,GetEnv    ( 'PATH   ' ) ) ;
                    i f  s = ' '  then
                      WriteLn     ( ParamStr      ( 1 ) ,' |_|not |_|Found  |_|i n|_|PATH ' )
                    e l s e
                      W r i t e l n(ParamStr      ( 1 ) ,' |_|Found  |_|i n|_|PATH |_|a t|_|',s) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.14        FSplit

Declaration:      Procedure  FSplit  (path:    pathstr;
                 var  dir:    dirstr;  var  name:    namestr;  var  ext:    extstr);

Description:      FSplit  splits  a  full  file  name  into  3  parts  :  A  Path,  a  Name  and  an  extension  (in  ext.)
                 Under linux, the extension is taken to be all letters after the last dot (.).

       Errors:    None.

     See also:    FSearch (47)


                 Listing:  dosex/ex12.pp
                                                                                  47

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example12      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e F S p l i t  f u n c t i o n.  }


                 v a r
                    Path   , Name   , Ext    :  s t r i n g;
                 b e g i n
                    F S p l i t(ParamStr       ( 1 ) ,Path  , Name   , Ext  ) ;
                    WriteLn     ( ' S p l i t t e d|_|',ParamStr     ( 1 ) ,' |_|i n: ') ;
                    WriteLn     ( ' Path   |_||_||_||_||_|:,|_|'Path) ;
                    WriteLn     ( ' Name   |_||_||_||_||_|:,|_|'Name) ;
                    WriteLn     ( ' E x t e n s i o n: |_|',Ext ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.15        GetCBreak

Declaration:      Procedure  GetCBreak  (var  breakvalue:    boolean);

Description:      GetCBreak gets the status of CTRL-Break checking under dos.  When BreakValue is false,
                 then dos only checks for the CTRL-Break key-press when I/O is performed.  When it is set
                 to True, then a check is done at every system call.

       Errors:    Under Linux, this exists but is not implemented, i.e.  the call does nothing.

     See also:    SetCBreak (54)
                 2.3.16        GetDate

Declaration:      Procedure  GetDate  (var  year,  month,  mday,  wday:    word);

Description:      GetDate returns the system's date.  Year is a number in the range 1980..2099.mday is the
                 day of the month, wday is the day of the week, starting with Sunday as day 0.

       Errors:    None.

     See also:    GetTime (51),SetDate (54)


                 Listing:  dosex/ex2.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example2      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e GetDate       f u n c t i o n.  }


                 c o n s t
                    DayStr     : a r r a y[ 0 . . 6 ]of    s t r i n g[ 3 ] = ('Sun  ' ,' Mon  ' , 'Tue   ', ' Wed  ' , 'Thu   ', '*
 * F r i' , 'Sat   ') ;
                    MonthStr      : a r r a y[ 1 . . 1 2 ] of   s t r i n g[ 3 ] = ('Jan  ' , 'Feb  ' , 'Mar   ' ,' Apr  ' , 'May  *
 * ' ,' Jun  ' ,
                                                                                   ' J u l' , 'Aug  ' , ' Sep  ' ,' Oct  ' , 'Nov  *
 * ' ,' Dec  ' ) ;
                 v a r
                    Year   , Month    ,Day   ,WDay     :   word   ;
                 b e g i n
                    GetDate     ( Year   , Month    ,Day   ,WDay   ) ;
                    WriteLn     ( ' C u r r e n t|_|d a t'e) ;
                    WriteLn     ( DayStr     [WDay    ] ,' , |_|',Day  , ' |_|',MonthStr      [Month    ] , ' |_|',Year  , ' . ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                  48

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 2.3.17        GetEnv

Declaration:      Function  GetEnv  (EnvVar:    String)  :    String;

Description:      Getenv returns the value of the environment variable EnvVar.  Under linux, case is impor-
                 tant when looking for EnvVar.  When there is no environment variable EnvVar defined, an
                 empty string is returned.

       Errors:    None.

     See also:    EnvCount (44), EnvStr (44)


                 Listing:  dosex/ex14.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example14      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e GetEnv       f u n c t i o n.  }


                 b e g i n
                    WriteLn     ( ' C u r r e n t|_|PATH |_|i s|_|',GetEnv    ( 'PATH   ' ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.18        GetFAttr

Declaration:      Procedure  GetFAttr  (var  F;  var  Attr:    word);

Description:      GetFAttr  returns  the  file  attributes  of  the  file-variable  f.   F  can  be  a  untyped  or  typed
                 file,  or  of  type  Text.  f  must  have  been  assigned,  but  not  opened.  The  attributes  can  be
                 examined with the following constants :

                      oReadOnly  =  01h

                      oHidden  =  02h

                      oSysFile  =  04h

                      oVolumeId  =  08h

                      oDirectory  =  10h

                      oArchive  =  20h

                 Under linux, supported attributes are:

                      oDirectory

                      oReadOnly if the current process doesn't have access to the file.

                      oHidden for files whose name starts with a dot ('.').

       Errors:    Errors are reported in DosError

     See also:    SetFAttr (54)


                 Listing:  dosex/ex8.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e G e t F A t t r f u n c t i o n.  }
                                                                                  49

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 v a r
                    A t t r  :  Word   ;
                    f        :   F i l e;
                 b e g i n
                    A s s i g n( f, ParamStr      ( 1 ) ) ;
                    G e t F A t t r(f , A t t r) ;
                    WriteLn     ( ' F i l e|_|',ParamStr      ( 1 ) ,' |_|has |_|a t t r i b u t|e_|',A t t r) ;
                    i f  ( A t t r  and    $20  )<>0     then     WriteLn     ('- |_|A r c h i v e') ;
                    i f  ( A t t r  and    $10  )<>0     then     WriteLn     ('- |_|D i r e c t o r'y) ;
                    i f  ( A t t r  and    $4 )<>0     then     WriteLn     ( '- |_|Read  - Only   ' ) ;
                    i f  ( A t t r  and    $2 )<>0     then     WriteLn     ( '- |_|System    ') ;
                    i f  ( A t t r  and    $1 )<>0     then     WriteLn     ( '- |_|Hidden    ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.19        GetFTime

Declaration:      Procedure  GetFTime  (var  F;  var  Time:    longint);

Description:      GetFTime returns the modification time of a file.  This time is encoded and must be decoded
                 with UnPackTime.  F must be a file type, which has been assigned, and opened.

       Errors:    Errors are reported in DosError

     See also:    SetFTime (55), PackTime (53),UnPackTime (56)


                 Listing:  dosex/ex9.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example9      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e GetFTime        f u n c t i o n.  }


                 F u n c t i o nL0  (w : word   ) : s t r i n g;
                 v a r
                    s   :  s t r i n g;
                 b e g i n
                    S t r( w , s ) ;
                    i f  w <10    then
                      L0 :=  ' 0 '+ s
                    e l s e
                      L0 :=  s ;
                 end  ;


                 v a r
                    f        :   F i l e;
                    Time     :   L o n g i n t;
                    DT       :  DateTime      ;
                 b e g i n
                    A s s i g n( f, ParamStr      ( 1 ) ) ;
                    Reset    ( f ) ;
                    GetFTime      ( f ,Time    ) ;
                    C l o s e( f ) ;
                    UnPackTime        (Time   , DT  ) ;
                    Write     (  'F i l e|_|',ParamStr       ( 1 ) ,' |_|i|s_|l a s|t_|m o d i f i e|d_|on|_|') ;
                    W r i t e l n ( L0 ( DT  .Month    ) , ' - ',L0  (DT  . Day  ) , ' - ',DT  . Year   ,
                                    ' |_|a t|_|',L0 (DT  . Hour   ) ,' : ', L0 ( DT  .Min   ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                                                                                  50

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 2.3.20        GetIntVec

Declaration:      Procedure  GetIntVec  (IntNo:    byte;  var  Vector:    pointer);

Description:      GetIntVec returns the address of interrupt vector IntNo.

       Errors:    Under non- dos operating systems, this call does nothing.

     See also:    SetIntVec (55)
                 2.3.21        GetLongName

Declaration:      function  GetLongName(var  p  :    String)  :    boolean;

Description:      This function is only implemented in the GO32V2 version of Free Pascal.

                 GetLongName changes the filename p to a long filename if the dos call to do this is successful.
                 The resulting string is the long file name corresponding to the short filename p.

                 The function returns True if the dos call was successful, False otherwise.

                 This  function  should  only  be  necessary  when  using  the  DOS  extender  under  Windows  95
                 and higher.

       Errors:    If the dos call was not succesfull, False is returned.

     See also:    GetShortName (51)
                 2.3.22        GetShortName

Declaration:      function  GetShortName(var  p  :    String)  :    boolean;

Description:      This function is only implemented in the GO32V2 version of Free Pascal.

                 GetShortName changes the filename p to a short filename if the dos call to do this is suc-
                 cessful.  The resulting string is the short file name corresponding to the long filename p.

                 The function returns True if the dos call was successful, False otherwise.

                 This  function  should  only  be  necessary  when  using  the  DOS  extender  under  Windows  95
                 and higher.

       Errors:    If the dos call was not successful, False is returned.

     See also:    GetLongName (51)
                 2.3.23        GetTime

Declaration:      Procedure  GetTime  (var  hour,  minute,  second,  sec100:    word);

Description:      GetTime  returns  the  system's  time.   Hour  is  a  on  a  24-hour  time  scale.   sec100  is  in
                 hundredth of a second.

       Errors:    None.

     See also:    GetDate (48), SetTime (55)


                 Listing:  dosex/ex3.pp
                                                                                  51

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example3      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e GetTime       f u n c t i o n.  }


                 F u n c t i o nL0  (w : word   ) : s t r i n g;
                 v a r
                    s   :  s t r i n g;
                 b e g i n
                    S t r( w , s ) ;
                    i f  w <10    then
                      L0 :=  ' 0 '+ s
                    e l s e
                      L0 :=  s ;
                 end  ;


                 v a r
                    Hour   , Min  , Sec  , HSec     :  word   ;
                 b e g i n
                    GetTime     ( Hour   , Min  , Sec  , HSec   ) ;
                    WriteLn     ( ' C u r r e n t|_|t i m'e) ;
                    WriteLn     ( L0  (Hour    ) ,' : ', L0 ( Min  ) , ' : ', L0 ( Sec  ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.24        GetVerify

Declaration:      Procedure  GetVerify  (var  verify:    boolean);

Description:      GetVerify returns the status of the verify flag under dos.  When Verify is True, then dos
                 checks data which are written to disk, by reading them after writing.  If  Verify is False,
                 then data written to disk are not verified.

       Errors:    Under linux, Verify is always True.

     See also:    SetVerify (55)
                 2.3.25        Intr

Declaration:      Procedure  Intr  (IntNo:    byte;  var  Regs:    registers);

Description:      Intr  executes  a  software  interrupt  number  IntNo  (must  be  between  0  and  255),  with
                 processor registers set to Regs.  After the interrupt call returned, the processor registers are
                 saved in Regs.

       Errors:    Under  linux  this  call  does  nothing,  because  interrupts  are  managed  by  the  kernel.  The
                 only allowed interrupt is 80h, the Linux kernel entry interrupt.

     See also:    MSDos (53), see the linux unit.
                 2.3.26        Keep

Declaration:      Procedure  Keep  (ExitCode:    word);

Description:      Keep terminates the program, but stays in memory.  This is used for TSR (Terminate Stay
                 Resident)  programs  which  catch  some  interrupt.   ExitCode  is  the  same  parameter  as  the
                 Halt function takes.



                                                                                  52

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    Under non-dos operating systems, this call does nothing.

     See also:    Halt ()
                 2.3.27        MSDos

Declaration:      Procedure  MSDos  (var  regs:    registers);

Description:      MSDos executes an MS-dos call (int 21h).  This is the same as doing a Intr call with an
                 interrupt number of 21h.

       Errors:    None.

     See also:    Intr (52)
                 2.3.28        PackTime

Declaration:      Procedure  PackTime  (var  T:  datetime;  var  P:  longint);

Description:      UnPackTime converts the date and time specified in T to a packed-time format which can
                 be fed to SetFTime.

       Errors:    None.

     See also:    SetFTime (55), FindFirst (46), FindNext (47), UnPackTime (56)


                 Listing:  dosex/ex4.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example4      ;
                 u s e s Dos   ;


                 {  Program       to    d e m o n s t r a t et h e PackTime        and    UnPackTime         f u n c t i o n s.  }


                 v a r
                    DT       :  DateTime      ;
                    Time     :   l o n g i n t;
                 b e g i n
                    with     DT   do
                      b e g i n
                         Year   : = 1 9 9 8 ;
                         Month    : = 1 1 ;
                         Day   : = 1 1 ;
                         Hour   : = 1 1 ;
                         Min   : = 1 1 ;
                         Sec   : = 1 1 ;
                      end  ;
                    PackTime      ( DT , Time   ) ;
                    WriteLn     ( ' Packed    |_|Time   |_|: |_|',Time ) ;
                    UnPackTime        (Time   , DT  ) ;
                    WriteLn     ( ' Unpacked      |_|Again   : ') ;
                    with     DT   do
                      b e g i n
                         WriteLn      (' Year   |_||_|',Year  ) ;
                         WriteLn      (' Month    |_|',Month    ) ;
                         WriteLn      (' Day   |_||_||_|',Day) ;
                         WriteLn      (' Hour   |_||_|',Hour  ) ;
                         WriteLn      (' Min   |_||_||_|',Min) ;
                                                                                  53

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                         WriteLn      (' Sec   |_||_||_|',Sec) ;
                      end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 2.3.29        SetCBreak

Declaration:      Procedure  SetCBreak  (breakvalue:    boolean);

Description:      SetCBreak sets the status of CTRL-Break checking under dos.  When BreakValue is false,
                 then dos only checks for the CTRL-Break key-press when I/O is performed.  When it is set
                 to True, then a check is done at every system call.

       Errors:    Under Linux, this call exists but is not implemented, i.e.  it does nothing.

     See also:    GetCBreak (48)
                 2.3.30        SetDate

Declaration:      Procedure  SetDate  (year,month,day:    word);

Description:      SetDate sets the system's internal date.  Year is a number between 1980 and 2099.

       Errors:    On a linux machine, this is not implemented (allthough a procedure exists, it just doesn't
                 do anything.  The setting of the date is a root-only privilege, and is hence not implemented.

     See also:    Dos:GetDate (48), SetTime (55)
                 2.3.31        SetFAttr

Declaration:      Procedure  SetFAttr  (var  F;  Attr:    word);

Description:      SetFAttr sets the file attributes of the file-variable F. F can be a untyped or typed file, or
                 of type Text.  F must have been assigned, but not opened.  The attributes can be a sum of
                 the following constants:

                      oReadOnly  =  01h

                      oHidden  =  02h

                      oSysFile  =  04h

                      oVolumeId  =  08h

                      oDirectory  =  10h

                      oArchive  =  20h

                      oAnyFile  =  3fh

       Errors:    Errors are reported in DosError.  Under linux the call exists, but is not implemented, i.e.
                 it does nothing.

     See also:    GetFAttr (49)



                                                                                  54

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 2.3.32        SetFTime

Declaration:      Procedure  SetFTime  (var  F;  Time:    longint);

Description:      SetFTime  sets  the  modification  time  of  a  file,  this  time  is  encoded  and  must  be  encoded
                 with PackTime.  F must be a file type, which has been assigned, and opened.

       Errors:    Errors are reported in DosError

     See also:    GetFTime (50), PackTime (53),UnPackTime (56)
                 2.3.33        SetIntVec

Declaration:      Procedure  SetIntVec  (IntNo:    byte;  Vector:    pointer);

Description:      SetIntVec  sets  interrupt  vector  IntNo  to  Vector.   Vector  should  point  to  an  interrupt
                 procedure.

       Errors:    Under non- dos operating systems, this call does nothing.

     See also:    GetIntVec (51)
                 2.3.34        SetTime

Declaration:      Procedure  SetTime  (hour,minute,second,sec100:    word);

Description:      SetTime sets the system's internal clock.  The Hour parameter is on a 24-hour time scale.

       Errors:    this call exists, but is not implemented on linux, as setting the time is a root-only privilege.

     See also:    Dos:GetTime (51), SetDate (54)
                 2.3.35        SetVerify

Declaration:      Procedure  SetVerify  (verify:    boolean);

Description:      SetVerify sets the status of the verify flag under dos.  When Verify is True,  then dos
                 checks data which are written to disk, by reading them after writing.  If  Verify is False,
                 then data written to disk are not verified.

       Errors:    Under linux, Verify is always True.

     See also:    SetVerify (55)
                 2.3.36        SwapVectors

Declaration:      Procedure  SwapVectors  ;

Description:      SwapVectors swaps the contents of the internal table of interrupt vectors with the current
                 contents of the interrupt vectors.  This is called typically in before and after an Exec call.

       Errors:    Under linux this call does nothing, as the interrupt vectors are managed by the kernel.

     See also:    Exec (45), SetIntVec (55)

                                                                                  55

                 ___________________________________________________________________________2.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 2.3.37        UnPackTime

Declaration:      Procedure  UnPackTime  (p:    longint;  var  T:  datetime);

Description:      UnPackTime  converts  the  file-modification  time  in  p  to  a  DateTime  record.    The  file-
                 modification time can be returned by GetFTime, FindFirst or FindNext calls.

       Errors:    None.

     See also:    GetFTime (50), FindFirst (46), FindNext (47), PackTime (53)


                 For an example, see PackTime (53).



                                                                                  56


                 Chapter   3


                 The   DXELOAD   unit
                 3.1        Introduction


                 The dxeload unit was implemented by Pierre M"uller for dos, it allows to load a DXE file (an
                 object file with 1 entry point) into memory and return a pointer to the entry point.

                 It exists only for dos.
                 3.2        Constants,  types  and  variables



                 3.2.1       Constants

                 The following constant is the magic number, found in the header of a DXE file.


                 DXE_MAGIC    =  $31455844;
                 3.2.2       Types

                 The following record describes the header of a DXE file.  It is used to determine the magic
                 number of the DXE file and number of relocations that must be done when the object file i
                 sloaded in memory.


                 dxe_header  =  record
                     magic,
                     symbol_offset,
                     element_size,
                     nrelocs            :  longint;
                 end;
                 3.3        Functions  and  Procedures



                 3.3.1       dxe___load

Declaration:      function  dxe__ load(filename  :    string)  :    pointer;

Description:      dxe__ load loads the contents of the file filename into memory.  It performs the necessary
                 relocations in the object code, and returns then a pointer to the entry point of the code.



                                                                              57

          ___________________________________________________________________________3.3.___FUNCTIONS_AND_PROCEDURES_______________*
 *_____________
Errors:    If an error occurs during the load or relocations, Nil is returned.


          For an example, see the emu387 unit in the RTL.
                                                                           58


                 Chapter   4


                 The   EMU387   unit



                 The emu387 unit was written by Pierre M"uller for dos.  It sets up the coprocessor emulation
                 for FPC under dos.  It is not necessary to use this unit on other OS platforms because they
                 either simply do not run on a machine without coprocessor, or they provide the coprocessor
                 emulation themselves.

                 It shouldn't be necessary to use the function in this unit, it should be enough to place this
                 unit in the uses clause of your program to enable the coprocessor emulation under dos.  The
                 unit initialization code will try and load the coprocessor emulation code and initialize it.
                 4.1        Functions  and  procedures



                 4.1.1       npxsetup

Declaration:      procedure  npxsetup(prog__ name  :    string);

Description:      npxsetup checks whether a coprocessor is found.  If not, it loads the file wmemu387.dxe into
                 memory and initializes the code in it.

                 If the environment variable 387 is set to N, then the emulation will be loaded, even if there
                 is a coprocessor present.  If the variable doesn't exist, or is set to any other value, the unit
                 will try to detect the presence of a coprocessor unit.

                 The function searches the file wmemu387.dxe in the following way:

                     1.If the environment variable EMU387 is set, then it is assumed to point at the wmemu387.dxe
                       file.

                     2.if the environment variable EMU387 does not exist, then the function will take the path
                       part of  prog__ name and look in that directory for the file wmemu387.dxe.

                 It should never be necessary to call this function, because the initialization code of the unit
                 contains  a  call  to  the  function  with  as  an  argument  paramstr(0).   This  means  that  you
                 should deliver the file wmemu387.dxe together with your program.

       Errors:    If there is an error, an error message is printed to standard error, and the program is halted,
                 since any floating-point code is bound to fail anyhow.
                                                                              59


Chapter   5


The   GETOPTS   unit.



This document describes the GETOPTS unit for Free Pascal.  It was written for linux by
Micha"el Van Canneyt.  It now also works for all supported platforms.

The getopts unit provides a mechanism to handle command-line options in a structured way,
much  like  the  GNU  getopts  mechanism.  It  allows  you  to  define  the  valid  options  for  you
program, and the unit will then parse the command-line options for you, and inform you of
any errors.

The chapter is divided in 2 sections:


    o  The first section lists types, constants and variables from the interface part of the unit.

    o  The second section describes the functions defined in the unit.
5.1        Types,  Constants  and  variables  :



5.1.1       Constants

No__ Argument=0 :  Specifies that a long option does not take an argument.
Required__ Argument=1 :  Specifies that a long option needs an argument.
Optional__ Argument=2 :  Specifies that a long option optionally takes an argument.
EndOfOptions=#255 :  Returned by getopt, getlongopts to indicate that there are no more
options.
5.1.2       Types

TOption  =  record
   Name       :  String;
   Has_arg  :  Integer;
   Flag       :  PChar;
   Value     :  Char;
   end;
POption  =  ^TOption;


The option type is used to communicate the long options to GetLongOpts.  The Name field
is  the  name  of  the  option.  Has__ arg  specifies  if  the  option  wants  an  argument,  Flag  is  a
pointer to a char, which is set to Value, if it is non-nil.  POption is a pointer to a Option
record.  It is used as an argument to the GetLongOpts function.



                                                             60

                 ___________________________________________________________________________5.2.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                 5.1.3       Variables

                 OptArg:String  Is set to the argument of an option, if the option needs one.
                 Optind:Longint   Is  the  index  of  the  current  paramstr().   When  all  options  have  been
                 processed, optind is the index of the first non-option parameter.  This is a read-only variable.
                 Note that it can become equal to paramcount+1
                 OptErr:Boolean  Indicates whether getopt() prints error messages.
                 OptOpt:Char  In case of an error, contains the character causing the error.
                 5.2        Procedures  and  functions



                 5.2.1       GetLongOpts

Declaration:      Function  GetLongOpts  (Shortopts  :    String,  LongOpts  :    POption;  var  Longint  :
                 Longint  )  :    Char;

Description:      Returns  the  next  option  found  on  the  command-line,  taking  into  account  long  options
                 as  well.   If  no  more  options  are  found,  returns  EndOfOptions.   If  the  option  requires  an
                 argument,  it  is  returned  in  the  OptArg  variable.   ShortOptions  is  a  string  containing  all
                 possible  one-letter  options.   (see  Getopt  (61)  for  its  description  and  use)  LongOpts  is  a
                 pointer to the first element of an array of  Option records, the last of which needs a name
                 of zero length.  The function tries to match the names even partially (i.e.  --app will match
                 e.g.  the append option), but will report an error in case of ambiguity.  If the option needs an
                 argument, set Has__ arg to Required__ argument, if the option optionally has an argument,
                 set Has__ arg to Optional__ argument.  If the option needs no argument, set Has__ arg to zero.
                 Required arguments can be specified in two ways :

                     1. Pasted to the option :  --option=value

                     2. As a separate argument :  --option  value

                 Optional arguments can only be specified through the first method.

       Errors:    see Getopt (61), getopt (3)

     See also:    Getopt
                 5.2.2       Getopt

Declaration:      Function  Getopt  (Shortopts  :    String)  :    Char;

Description:      Returns the next option found on the command-line.  If no more options are found, returns
                 EndOfOptions.  If  the  option  requires  an  argument,  it  is  returned  in  the  OptArg  variable.
                 ShortOptions  is  a  string  containing  all  possible  one-letter  options.  If  a  letter  is  followed
                 by  a  colon  (:),  then  that  option  needs  an  argument.   If  a  letter  is  followed  by  2  colons,
                 the option has an optional argument.  If the first character of  shortoptions is a '+' then
                 options following a non-option are regarded as non-options (standard Unix behavior).  If it
                 is a '-', then all non-options are treated as arguments of a option with character #0.  This
                 is  useful  for  applications  that  require  their  options  in  the  exact  order  as  they  appear  on
                 the command-line.  If the first character of  shortoptions is none of the above, options and
                 non-options are permuted, so all non-options are behind all options.  This allows options and
                 non-options to be in random order on the command line.

       Errors:    Errors are reported through giving back a '?'  character.  OptOpt then gives the character
                 which caused the error.  If  OptErr is True then getopt prints an error-message to stdout.

     See also:    GetLongOpts (61), getopt (3)



                                                                                  61

 ___________________________________________________________________________5.2.___PROCEDURES_AND_FUNCTIONS________________________*
 *____
________________________________________________________________________________________________________________________________
 program       t e s t o p t;


 {  Program       to    d e p m o n s t r a t et h e g e t o p t s f u n c t i o n.  }


 {
    V a l i d  c a l l s to    t h i s program       a r e
    o p t e x --  v e r b o s e--   add   me   --  d e l e t e you
    o p t e x --  append     --   c r e a t e c h i l d
    o p t e x - ab   - c   me  -  d  you
    and    so   on
 }
 u s e s  g e t o p t s;


 v a r  c  :   c h a r;
        o p t i o n i n d e x:  L o n g i n t;
        t h e o p t s :  a r r a y[ 1 . . 7 ] of   TOption      ;


 b e g i n
    with     t h e o p t s[ 1 ] do
      b e g i n
        name   := ' add  ' ;
        h a s __a r g: = 1 ;
        f l a g:= n i l;
        v a l u e:=#0;
    end   ;
    with     t h e o p t s[ 2 ] do
      b e g i n
        name   := ' append    ' ;
        h a s __a r g: = 0 ;
        f l a g:= n i l;
        v a l u e:=#0;
    end   ;
    with     t h e o p t s[ 3 ] do
      b e g i n
        name   := ' d e l e t e';
        h a s __a r g: = 1 ;
        f l a g:= n i l;
        v a l u e:=#0;
    end   ;
    with     t h e o p t s[ 4 ] do
      b e g i n
        name   := ' v e r b o s e';
        h a s __a r g: = 0 ;
        f l a g:= n i l;
        v a l u e:=#0;
    end   ;
    with     t h e o p t s[ 5 ] do
      b e g i n
        name   := ' c r e a t e';
        h a s __a r g: = 1 ;
        f l a g:= n i l;
        v a l u e:= ' c'
    end   ;
    with     t h e o p t s[ 6 ] do
      b e g i n
        name   := ' f i l e' ;
        h a s __a r g: = 1 ;
                                                                  62

 ___________________________________________________________________________5.2.___PROCEDURES_AND_FUNCTIONS________________________*
 *____
        f l a g:= n i l;
        v a l u e:=#0;
    end   ;
    with     t h e o p t s[ 7 ] do
      b e g i n
        name   := ' ' ;
        h a s __a r g: = 0 ;
        f l a g:= n i l;
    end   ;
    c :=#0;
    r e p e a t
        c:=  g e t l o n g o p t(s' abc  :d : 0 1 2 ', @ t h e o p t s[ 1 ] ,o p t i o n i n d e)x;
        case    c   of
           ' 1 ' ,' 2 ', ' 3 ', ' 4 ', ' 5 ', ' 6 ', ' 7 ', ' 8 ', ' 9 '  :
               b e g i n
               w r i t e l n( ' Got  |_|o p t i n d|_|: |_|',c)
               end  ;
           # 0  :   b e g i n
                    w r i t e ( ' Long   |_|o p t i o|n_|: |_|',t h e o p t[so p t i o n i n d e]x.name  ) ;
                    i f  t h e o p t s[o p t i o n i n d e x] .h a s __a r>g0  then
                        w r i t e l n( ' |_|With  |_|v a l u|e_||_|: |_|',o p t a)r g
                    e l s e
                        w r i t e l n
                    end  ;
           ' a '  :   w r i t e l n( ' O p t i o n|_|a. ') ;
           ' b '  :   w r i t e l n( ' O p t i o n|_|b. ') ;
           ' c '  :   w r i t e l n( ' O p t i o n|_|c|_|: |_|',o p t a r g) ;
           ' d '  :   w r i t e l n( ' O p t i o n|_|d|_|: |_|',o p t a r g) ;
           ' ? ' , ' : ' :   w r i t e l n( ' E r r o r|_|w i t h|_|opt|_|: |_|',o p t o p)t;
      end  ;   {  c a s e }
   u n t i l c=  e n d o f o p t i o n;s
   i f  o p t i n d<= paramcount         then
        b e g i n
        w r i t e ( 'Non   |_|o p t i o n|s_|: |_|') ;
        w h i l e o p t i n d<= paramcount         do
           b e g i n
           w r i t e ( p a r a m s t r(o p t i n d) ,' |_|') ;
           i n c( o p t i n d)
           end   ;
        w r i t e l n
        end
_end__._________________________________________________________________________________________________________________________


                                                                  63


Chapter   6


The   GPM   unit
6.1        Introduction


The GPM unit implements an interface to filelibgpm, the console program for mouse handling.
This unit was created by Peter Vreman, and is only available on linux.

When this unit is used, your program is linked to the C libraries, so you must take care of
the C library version.  Also, it will only work with version 1.17 or higher of the libgpm library.
6.2        Constants,  types  and  variables



6.2.1       constants

The following constants are used to denote filenames used by the library:


_PATH_VARRUN  =  '/var/run/';
_PATH_DEV       =  '/dev/';
GPM_NODE_DIR  =  _PATH_VARRUN;
GPM_NODE_DIR_MODE  =  0775;
GPM_NODE_PID    =  '/var/run/gpm.pid';
GPM_NODE_DEV    =  '/dev/gpmctl';
GPM_NODE_CTL    =  GPM_NODE_DEV;
GPM_NODE_FIFO  =  '/dev/gpmdata';


The following constants denote the buttons on the mouse:


GPM_B_LEFT     =  4;
GPM_B_MIDDLE  =  2;
GPM_B_RIGHT    =  1;


The following constants define events:


GPM_MOVE  =  1;
GPM_DRAG  =  2;
GPM_DOWN  =  4;
GPM_UP  =  8;
GPM_SINGLE  =  16;
GPM_DOUBLE  =  32;



                                                             64

__________________________________________________________________6.2.___CONSTANTS,_TYPES_AND_VARIABLES____________________________*
 *___
GPM_TRIPLE  =  64;
GPM_MFLAG  =  128;
GPM_HARD  =  256;
GPM_ENTER  =  512;
GPM_LEAVE  =  1024;


The following constants are used in defining margins:


GPM_TOP  =  1;
GPM_BOT  =  2;
GPM_LFT  =  4;
GPM_RGT  =  8;
6.2.2       Types

The following general types are defined:


   TGpmEtype  =  longint;
   TGpmMargin  =  longint;


The following type describes an event; it is passed in many of the gpm functions.


PGpmEvent  =  ^TGpmEvent;
TGpmEvent  =  record
   buttons  :  byte;
   modifiers  :  byte;
   vc  :  word;
   dx  :  word;
   dy  :  word;
   x  :  word;
   y  :  word;
   EventType  :  TGpmEType;
   clicks  :  longint;
   margin  :  TGpmMargin;
end;
TGpmHandler=function(var  event:TGpmEvent;clientdata:pointer):longint;cdecl;


The following types are used in connecting to the gpm server:


PGpmConnect  =  ^TGpmConnect;
TGpmConnect  =  record
   eventMask  :  word;
   defaultMask  :  word;
   minMod  :  word;
   maxMod  :  word;
   pid  :  longint;
   vc  :  longint;
end;


The following type is used to define regions of interest


PGpmRoi  =  ^TGpmRoi;
TGpmRoi  =  record
   xMin  :  integer;



                                                                 65

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    xMax  :  integer;
                    yMin  :  integer;
                    yMax  :  integer;
                    minMod  :  word;
                    maxMod  :  word;
                    eventMask  :  word;
                    owned  :  word;
                    handler  :  TGpmHandler;
                    clientdata  :  pointer;
                    prev  :  PGpmRoi;
                    next  :  PGpmRoi;
                 end;
                 6.2.3       Variables

                 The following variables are imported from the gpm library


                 gpm_flag                  :  longint;cvar;external;
                 gpm_fd                      :  longint;cvar;external;
                 gpm_hflag                 :  longint;cvar;external;
                 gpm_morekeys            :  Longbool;cvar;external;
                 gpm_zerobased          :  Longbool;cvar;external;
                 gpm_visiblepointer  :  Longbool;cvar;external;
                 gpm_mx                      :  longint;cvar;external;
                 gpm_my                      :  longint;cvar;external;
                 gpm_timeout             :  TTimeVal;cvar;external;
                 _gpm_buf                  :  array[0..0]  of  char;cvar;external;
                 _gpm_arg                  :  ^word;cvar;external;
                 gpm_handler             :  TGpmHandler;cvar;external;
                 gpm_data                  :  pointer;cvar;external;
                 gpm_roi_handler       :  TGpmHandler;cvar;external;
                 gpm_roi_data            :  pointer;cvar;external;
                 gpm_roi                    :  PGpmRoi;cvar;external;
                 gpm_current_roi       :  PGpmRoi;cvar;external;
                 gpm_consolefd          :  longint;cvar;external;
                 Gpm_HandleRoi          :  TGpmHandler;cvar;external;
                 6.3        Functions  and  procedures



                 6.3.1       Gpm___AnyDouble

Declaration:      function  Gpm__ AnyDouble(EventType  :    longint)  :    boolean;

Description:      Gpm__ AnyDouble returns True if EventType contains the GPM__ DOUBLE flag, False otherwise.

       Errors:    None.

     See also:    Gpm__ StrictSingle (71), Gpm__ AnySingle (66), Gpm__ StrictDouble (71), Gpm__ StrictTriple (72),
                 Gpm__ AnyTriple (67)
                 6.3.2       Gpm___AnySingle

Declaration:      function  Gpm__ AnySingle(EventType  :    longint)  :    boolean;



                                                                                  66

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      Gpm__ AnySingle returns True if EventType contains the GPM__ SINGLE flag, False otherwise.

       Errors:

     See also:    Gpm__ StrictSingle  (71),  Gpm__ AnyDoubmle  (66),  Gpm__ StrictDouble  (71),  Gpm__ StrictTriple
                 (72), Gpm__ AnyTriple (67)
                 6.3.3       Gpm___AnyTriple

Declaration:      function  Gpm__ AnyTriple(EventType  :    longint)  :    boolean;

Description:

       Errors:

     See also:    Gpm__ StrictSingle  (71),  Gpm__ AnyDoubmle  (66),  Gpm__ StrictDouble  (71),  Gpm__ StrictTriple
                 (72), Gpm__ AnySingle (66)
                 6.3.4       Gpm___Close

Declaration:      function  Gpm__ Close:longint;cdecl;external;

Description:      Gpm__ Close closes the current connection, and pops the connection stack; this means that
                 the previous connection becomes active again.

                 The function returns -1 if the current connection is not the last one, and it returns 0 if the
                 current connection is the last one.

       Errors:    None.

     See also:    Gpm__ Open (70)


                 for an example, see Gpm__ GetEvent (68).
                 6.3.5       Gpm___FitValues

Declaration:      function  Gpm__ FitValues(var  x,y:longint):longint;cdecl;external;

Description:      Gpm__ fitValues changes x and y so they fit in the visible screen.  The actual mouse pointer
                 is not affected by this function.

       Errors:    None.

     See also:    Gpm__ FitValuesM (67),
                 6.3.6       Gpm___FitValuesM

Declaration:      function  Gpm__ FitValuesM(var  x,y:longint;  margin:longint):longint;cdecl;external;

Description:      Gpm__ FitValuesM chnages x and y so they fit in the margin indicated by margin.  If margin
                 is -1, then the values are fitted to the screen.  The actual mouse pointer is not affected by
                 this function.

       Errors:    None.

     See also:    Gpm__ FitValues (67),

                                                                                  67

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 6.3.7       Gpm___GetEvent

Declaration:      function  Gpm__ GetEvent(var  Event:TGpmEvent):longint;cdecl;external;

Description:      Gpm__ GetEvent Reads an event from the file descriptor gpm__ fd.  This file is only for internal
                 use and should never be called by a client application.

                 It returns 1 on succes, and -1 on failue.

       Errors:    On error, -1 is returned.

     See also:    seeflGpm__ GetSnapshotGpmGetSnapshot


                 Listing:  gpmex/gpmex.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 program       gpmex   ;


                 {
                    Example       program       to   d e m o n s t r a t et h e  u s e  o f  t h e  gpm     u n i t.
                 }


                 u s e s gpm   ;


                 v a r
                    c o n n e c t :   TGPMConnect        ;
                    e v e n t  :  t g p m e v e n t;


                 b e g i n
                    c o n n e c t.EventMask       := GPM__MOVE       or   GPM__DRAG       or   GPM__DOWN       or   GPM__UP    ;
                    c o n n e c t.D e f a u l t M a s:k= 0 ;
                    c o n n e c t.MinMod     : = 0 ;
                    c o n n e c t.MaxMod     : = 0 ;
                    i f  Gpm__Open     ( c o n n e c t,0)=-1      then
                        b e g i n
                        W r i t e l n('No  |_|mouse  |_|h a n d l e|r_|p r e s e n.t') ;
                        Halt   ( 1 ) ;
                        end  ;
                    W r i t e l n(' C l i c k|_|r i g h|t_|b u t t o|n_|to|_|end. ') ;
                    Repeat
                        gpm __getevent       (E v e n t) ;
                        With    E v e n t  do
                           b e g i n
                               Write   ( ' Pos  |_|= |_|(,'X, ' , ', Y , ' ) |_|B u t t o n|s_|: |_|()';
                               i f  ( b u t t o n s and    Gpm __b __left   )<>0     then
                                  w r i t e( ' l e f t|_|') ;
                               i f  ( b u t t o n s and    Gpm __b __right    )<>0    then
                                  w r i t e( ' r i g h t|_|') ;
                               i f  ( b u t t o n s and   Gpm __b __middle     )<>0     then
                                  Write    ( 'm i d d l e|_|') ;
                               Write   ( ' ) |_|E v e n t|_|: |_|') ;
                               Case    EventType         and    $F   of
                                  GPM__MOVE     :   w r i t e(' Move   ' ) ;
                                  GPM__DRAG     :   w r i t e(' Drag   ' ) ;
                                  GPM__DOWN     :   w r i t e(' Down   ' ) ;
                                  GPM__UP    :  w r i t e( 'Up  ' ) ;
                               end  ;
                               W r i t e l n;
                           end   ;
                    U n t i l ( E v e n t. B u t t o n s and    gpm __b __right    )<>0;
                    gpm __close     ;



                                                                                  68

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 6.3.8       Gpm___GetLibVersion

Declaration:      function  Gpm__ GetLibVersion(var  where:longint):pchar;cdecl;external;

Description:      Gpm__ GetLibVersion returns a pointer to a version string, and returns in where an integer
                 representing the version.  The version string represents the version of the gpm library.

                 The return value is a pchar, which should not be dealloacted, i.e.  it is not on the heap.

       Errors:    None.

     See also:    Gpm__ GetServerVersion (69)
                 6.3.9       Gpm___GetServerVersion

Declaration:      function  Gpm__ GetServerVersion(var  where:longint):pchar;cdecl;external;

Description:      Gpm__ GetServerVersion  returns  a  pointer  to  a  version  string,  and  returns  in  where  an
                 integer representing the version.  The version string represents the version of the gpm server
                 program.

                 The return value is a pchar, which should not be dealloacted, i.e.  it is not on the heap.

       Errors:    If the gpm program is not present, then the function returns Nil

     See also:    Gpm__ GetLibVersion (69)
                 6.3.10        Gpm___GetSnapshot

Declaration:      function  Gpm__ GetSnapshot(var  Event:TGpmEvent):longint;cdecl;external;

Description:      Gpm__ GetSnapshot returns the picture that the server has of the current situation in Event.
                 This  call  will  not  read  the  current  situation  from  the  mouse  file  descriptor,  but  returns  a
                 buffered version.  The meaning of the fields is as follows:

                 x,y current position of the cursor.

                 dx,dy   size of the window.

                 vc number of te virtual console.

                 modifiers     keyboard shift state.

                 buttons     buttons which are currently pressed.

                 clicks  number of clicks (0,1 or 2).

                 The function returns the number of mouse buttons, or -1 if this information is not available.

       Errors:    None.

     See also:    Gpm__ GetEvent (68)


                                                                                  69

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 6.3.11        Gpm___LowerRoi

Declaration:      function  Gpm__ LowerRoi(which:PGpmRoi;  after:PGpmRoi):PGpmRoi;cdecl;external;

Description:      Gpm__ LowerRoi lowers the region of interest which after after.  If  after is Nil, the region
                 of interest is moved to the bottom of the stack.

                 The return value is the new top of the region-of-interest stack.

       Errors:    None.

     See also:    Gpm__ RaiseRoi (71), Gpm__ PopRoi (70), Gpm__ PushRoi (70)
                 6.3.12        Gpm___Open

Declaration:      function  Gpm__ Open(var  Conn:TGpmConnect;  Flag:longint):longint;cdecl;external;

Description:      Gpm__ Open opens a new connection to the mouse server.  The connection is described by the
                 fields of the conn record:

                 EventMask        A bitmask of the events the program wants to receive.

                 DefaultMask         A bitmask to tell the library which events get their default treatment (text
                       selection).

                 minMod       the minimum amount of modifiers needed by the program.

                 maxMod        the maximum amount of modifiers needed by the program.

                 if Flag is 0, then the application only receives events that come from its own terminal device.
                 If it is negative it will receive all events.  If the value is positive then it is considered a console
                 number to which to connect.

                 The return value is -1 on error, or the file descriptor used to communicate with the client.
                 Under an X-Term the return value is -2.

       Errors:    On Error, the return value is -1.

     See also:    Gpm__ Open (70)


                 for an example, see Gpm__ GetEvent (68).
                 6.3.13        Gpm___PopRoi

Declaration:      function  Gpm__ PopRoi(which:PGpmRoi):PGpmRoi;cdecl;external;

Description:      Gpm__ PopRoi pops the topmost region of interest from the stack.  It returns the next element
                 on the stack, or Nil if the current element was the last one.

       Errors:    None.

     See also:    Gpm__ RaiseRoi (71), Gpm__ LowerRoi (70), Gpm__ PushRoi (70)
                 6.3.14        Gpm___PushRoi

Declaration:      function  Gpm__ PushRoi(x1:longint;  y1:longint;  X2:longint;  Y2:longint;  mask:longint;
                 fun:TGpmHandler;  xtradata:pointer):PGpmRoi;cdecl;external;
                                                                                  70

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      Gpm__ PushRoi puts a new region of interest on the stack.  The region of interest is defined
                 by a rectangle described by the corners (X1,Y1) and (X2,Y2).

                 The mask describes which events the handler fun will handle; ExtraData will be put in the
                 xtradata field of the TGPM__ Roi record passed to the fun handler.

       Errors:    None.

     See also:    Gpm__ RaiseRoi (71), Gpm__ PopRoi (70), Gpm__ LowerRoi (70)
                 6.3.15        Gpm___RaiseRoi

Declaration:      function  Gpm__ RaiseRoi(which:PGpmRoi;  before:PGpmRoi):PGpmRoi;cdecl;external;

Description:      Gpm__ RaiseRoi  raises  the  region  of  interest  which  till  it  is  on  top  of  region  before.   If
                 before is nil then the region is put on top of the stack.  The returned value is the top of the
                 stack.

       Errors:    None.

     See also:    Gpm__ PushRoi (70), Gpm__ PopRoi (70), Gpm__ LowerRoi (70)
                 6.3.16        Gpm___Repeat

Declaration:      function  Gpm__ Repeat(millisec:longint):longint;cdecl;external;

Description:      Gpm__ Repeat  returns  1  of  no  mouse  event  arrives  in  the  next  millisec  miiliseconds,  it
                 returns 0 otherwise.

       Errors:    None.

     See also:    Gpm__ GetEvent (68)
                 6.3.17        Gpm___StrictDouble

Declaration:      function  Gpm__ StrictDouble(EventType  :    longint)  :    boolean;

Description:      Gpm__ StrictDouble  returns  true  if  EventType  contains  only  a  doubleclick  event,  False
                 otherwise.

       Errors:    None.

     See also:    Gpm__ StrictSingle (71), Gpm__ AnyTriple (67), Gpm__ AnyDouble (66), Gpm__ StrictTriple (72),
                 Gpm__ AnySingle (66)
                 6.3.18        Gpm___StrictSingle

Declaration:      function  Gpm__ StrictSingle(EventType  :    longint)  :    boolean;

Description:      Gpm__ StrictDouble  returns  True  if  EventType  contains  only  a  singleclick  event,  False
                 otherwise.

       Errors:    None.

     See also:    Gpm__ AnyTriple (67), Gpm__ StrictDouble (71), Gpm__ AnyDouble (66), Gpm__ StrictTriple (72),
                 Gpm__ AnySingle (66)

                                                                                  71

                 ___________________________________________________________________________6.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 6.3.19        Gpm___StrictTriple

Declaration:      function  Gpm__ StrictTriple(EventType  :    longint)  :    boolean;

Description:      Gpm__ StrictTriple  returns  true  if  EventType  contains  only  a  triple  click  event,  False
                 otherwise.

       Errors:    None.

     See also:    Gpm__ AnyTriple (67), Gpm__ StrictDouble (71), Gpm__ AnyDouble (66), Gpm__ StrictSingle (71),
                 Gpm__ AnySingle (66)

                                                                                  72


Chapter   7


The   GO32   unit



This  chapter  of  the  documentation  describe  the  GO32  unit  for  the  Free  Pascal  compiler
under  dos.  It  was  donated  by  Thomas  Schatzl  (tom__ at__ work@geocities.com),  for  which
my thanks.  This unit was first written for dos by Florian Klaempfl.  This chapter is divided
in  four  sections.  The  first  two  sections  are  an  introduction  to  the  GO32  unit.  The  third
section  lists  the  pre-defined  constants,  types  and  variables.  The  last  section  describes  the
functions which appear in the interface part of the GO32 unit.
7.1        Introduction


These  docs  contain  information  about  the  GO32  unit.  Only  the  GO32V2  DPMI  mode  is
discussed  by  me  here  due  to  the  fact  that  new  applications  shouldn't  be  created  with  the
older GO32V1 model.  The go32v2 version is much more advanced and better.  Additionally
a lot of functions only work in DPMI mode anyway.  I hope the following explanations and
introductions aren't too confusing at all.  If you notice an error or bug send it to the FPC
mailing list or directly to me.  So let's get started and happy and error free coding I wish
you....                                                                       Thomas Schatzl, 25.  August 1998
7.2        Protected  mode  memory  organization



7.2.1       What  is  DPMI

The dos Protected Mode Interface helps you with various aspects of protected mode pro-
gramming.   These  are  roughly  divided  into  descriptor  handling,  access  to  dos  memory,
management of interrupts and exceptions, calls to real mode functions and other stuff.  Ad-
ditionally it automatically provides swapping to disk for memory intensive applications.  A
DPMI  host  (either  a  Windows  dos  box  or  CWSDPMI.EXE)  provides  these  functions  for
your programs.
7.2.2       Selectors  and  descriptors

Descriptors are a bit like real mode segments; they describe (as the name implies) a memory
area in protected mode.  A descriptor contains information about segment length, its base
address and the attributes of it (i.e.  type,  access rights,  ...).  These descriptors are stored
internally  in  a  so-called  descriptor  table,  which  is  basically  an  array  of  such  descriptors.
Selectors are roughly an index into this table.  Because these 'segments' can be up to 4 GB
                                                             73

____________________________________________________7.2.___PROTECTED_MODE_MEMORY_ORGANIZATION______________________________________*
 *___
in  size,  32  bits  aren't  sufficient  anymore  to  describe  a  single  memory  location  like  in  real
mode.  48 bits are now needed to do this, a 32 bit address and a 16 bit sized selector.  The
GO32 unit provides the tseginfo record to store such a pointer.  But due to the fact that most
of the time data is stored and accessed in the %ds selector, FPC assumes that all pointers
point to a memory location of this selector.  So a single pointer is still only 32 bits in size.
This value represents the offset from the data segment base address to this memory location.
7.2.3       FPC  specialities

The %ds and %es selector MUST always contain the same value or some system routines may
crash when called.  The %fs selector is preloaded with the DOSMEMSELECTOR variable at
startup, and it MUST be restored after use, because again FPC relys on this for some func-
tions.  Luckily we asm programmers can still use the %gs selector for our own purposes, but
for how long ?  See also:  get__ cs (89), get__ ds (90), gett__ ss (97), allocate__ ldt__ descriptors (82),
free__ ldt__ descriptor  (88),  segment__ to__ descriptor  (103),  get__ next__ selector__ increment__ value
(91), get__ segment__ base__ address (96), set__ segment__ base__ address (105), set__ segment__ limit
(106), create__ code__ segment__ alias__ descriptor (85)
7.2.4       dos  memory  access

dos  memory  is  accessed  by  the  predefined  dosmemselector  selector;  the  GO32  unit  ad-
ditionally  provides  some  functions  to  help  you  with  standard  tasks,  like  copying  memory
from heap to dos memory and the likes.  Because of this it is strongly recommened to use
them, but you are still free to use the provided standard memory accessing functions which
use  48  bit  pointers.  The  third,  but  only  thought  for  compatibility  purposes,  is  using  the
mem[]-arrays.  These arrays map the whole 1 Mb dos space.  They shouldn't be used within
new  programs.  To  convert  a  segment:offset  real  mode  address  to  a  protected  mode  linear
address you have to multiply the segment by 16 and add its offset.  This linear address can
be used in combination with the DOSMEMSELECTOR variable.  See also:  dosmemget (87),
dosmemput (88), dosmemmove (87), dosmemfillchar (86), dosmemfillword (87), mem[]-arrays,
seg__ move (103), seg__ fillchar (102), seg__ fillword (103).
7.2.5       I/O  port  access

The I/O port access is done via the various inportb (99), outportb (100) functions which are
available.  Additionally Free Pascal supports the Turbo Pascal PORT[]-arrays but it is by no
means recommened to use them, because they're only for compatibility purposes.  See also:
outportb (100), inportb (99), PORT[]-arrays
7.2.6       Processor  access

These are some functions to access various segment registers (%cs, %ds, %ss) which makes
your work a bit easier.  See also:  get__ cs (89), get__ ds (90), get__ ss (97)
7.2.7       Interrupt  redirection

Interrupts are program interruption requests, which in one or another way get to the pro-
cessor;  there's  a  distinction  between  software  and  hardware  interrupts.   The  former  are
explicitely called by an 'int' instruction and are a bit comparable to normal functions.  Hard-
ware  interrupts  come  from  external  devices  like  the  keyboard  or  mouse.   Functions  that
handle hardware interrupts are called handlers.
                                                                 74

 ____________________________________________________7.2.___PROTECTED_MODE_MEMORY_ORGANIZATION_____________________________________*
 *____
 7.2.8       Handling  interrupts  with  DPMI

 The interrupt functions are real-mode procedures; they normally can't be called in protected
 mode  without  the  risk  of  an  protection  fault.  So  the  DPMI  host  creates  an  interrupt  de-
 scriptor table for the application.  Initially all software interrupts (except for int 31h,  2Fh
 and 21h function 4Ch) or external hardware interrupts are simply directed to a handler that
 reflects the interrupt in real-mode, i.e.  the DPMI host's default handlers switch the CPU to
 real-mode, issue the interrupt and switch back to protected mode.  The contents of general
 registers and flags are passed to the real mode handler and the modified registers and flags
 are  returned  to  the  protected  mode  handler.  Segment  registers  and  stack  pointer  are  not
 passed between modes.
 7.2.9       Protected  mode  interrupts  vs.  Real  mode  interrupts

 As mentioned before, there's a distinction between real mode interrupts and protected mode
 interrupts;  the  latter  are  protected  mode  programs,  while  the  former  must  be  real  mode
 programs.  To call a protected mode interrupt handler, an assembly 'int' call must be issued,
 while  the  other  is  called  via  the  realintr()  or  intr()  function.   Consequently,  a  real  mode
 interrupt then must either reside in dos memory (<1MB) or the application must allocate a
 real mode callback address via the get__ rm__ callback() function.
 7.2.10        Creating  own  interrupt  handlers

 Interrupt  redirection  with  FPC  pascal  is  done  via  the  set__ pm__ interrupt()  for  protected
 mode interrupts or via the set__ rm__ interrupt() for real mode interrupts.
 7.2.11        Disabling  interrupts

 The GO32 unit provides the two procedures disable() and enable() to disable and enable all
 interrupts.
 7.2.12        Hardware  interrupts

 Hardware interrupts are generated by hardware devices when something unusual happens;
 this could be a keypress or a mouse move or any other action.  This is done to minimize CPU
 time, else the CPU would have to check all installed hardware for data in a big loop (this
 method  is  called  'polling')  and  this  would  take  much  time.  A  standard  IBM-PC  has  two
 interrupt controllers, that are responsible for these hardware interrupts:  both allow up to 8
 different interrupt sources (IRQs, interrupt requests).  The second controller is connected to
 the first through IRQ 2 for compatibility reasons, e.g.  if controller 1 gets an IRQ 2, he hands
 the IRQ over to controller 2.  Because of this up to 15 different hardware interrupt sources
 can be handled.  IRQ 0 through IRQ 7 are mapped to interrupts 8h to Fh and the second
 controller (IRQ 8 to 15) is mapped to interrupt 70h to 77h.  All of the code and data touched
 by these handlers MUST be locked (via the various locking functions) to avoid page faults
 at interrupt time.  Because hardware interrupts are called (as in real mode) with interrupts
 disabled,  the  handler  has  to  enable  them  before  it  returns  to  normal  program  execution.
 Additionally  a  hardware  interrupt  must  send  an  EOI  (end  of  interrupt)  command  to  the
 responsible controller; this is acomplished by sending the value 20h to port 20h (for the first
 controller) or A0h (for the second controller).  The following example shows how to redirect
 the keyboard interrupt.

________________________________________________________________________________________________________________________________
 Program       K e y c l i c k;
                                                                  75

 ____________________________________________________7.2.___PROTECTED_MODE_MEMORY_ORGANIZATION_____________________________________*
 *____


 u s e s  c r t,
         go32    ;


 c o n s t k b d i n t =   $9 ;


 v a r  o l d i n t 9 __h a n d l e r: t s e g i n f o;
        n e w i n t 9 __h a n d l e r: t s e g i n f o;


        c l i c k p r o c:   p o i n t e r;


 {$ASMMODE        DIRECT     }
 p r o c e d u r ei n t 9 __h a n d l e;r  a s s e m b l e;r
 asm
      c l i
      p u s h a l
      movw    % c s :INT9__DS     ,  % ax
      movw    % ax  ,  % ds
      movw    % ax  ,  % e s
      movw    U__GO32__DOSMEMSELECTOR              ,  % ax
      movw    % ax  ,  % f s
      c a l l * __CLICKPROC
      p o p a l


      l j m p % c s :OLDHANDLER


 INT9__DS    :  . word    0
OLDHANDLER        :
                 .l o n g 0
                 .word    0
 end  ;


 p r o c e d u r eint9 __dummy      ;  b e g i n end   ;


 p r o c e d u r ec l i c k e r;
 b e g i n
         sound    ( 5 0 0 ) ;  d e l a y( 1 0 ) ; nosound     ;
 end  ;


 p r o c e d u r ec l i c k e r __d u m m;y b e g i n  end  ;


 p r o c e d u r ei n s t a l l __c l i c;k
 b e g i n
          c l i c k p r o c: =  @ c l i c k e r;
          l o c k __d a t(ac l i c k p r o c, s i z e o f( c l i c k p r o)c) ;
          l o c k __d a t(ad o s m e m s e l e c t o,r s i z e o f(d o s m e m s e l e c t o)r) ;


          l o c k __c o d(e@ c l i c k e r,
                           l o n g i n t(@clicker __dummy        )-  l o n g i n t(@ c l i c k e r) ) ;
          l o c k __c o d(e@ i n t 9 __h a n d l e,r
                           l o n g i n t(@int9 __dummy      )
                            -   l o n g i n t(@ i n t 9 __h a n d l e)r) ;
          n e w i n t 9 __h a n d l e.ro f f s e t: =  @ i n t 9 __h a n d l e;r
          n e w i n t 9 __h a n d l e.rsegment     : =   g e t __c s;
          g e t __p m __i n t e r r u(pktb d i n t,  o l d i n t 9 __h a n d l e)r;
         asm
              movw    %  ds  ,  % ax
              movw    %  ax  ,  INT9__DS
                                                                  76

 ____________________________________________________7.2.___PROTECTED_MODE_MEMORY_ORGANIZATION_____________________________________*
 *____
               movl    __OLDINT9__HANDLER          ,  %  eax
               movl   %  eax   , OLDHANDLER
              movw     4+  __OLDINT9__HANDLER          ,  % ax
              movw    %  ax  ,  4+ OLDHANDLER
         end   ;
          s e t __p m __i n t e r r u(pktb d i n t,  n e w i n t 9 __h a n d l e)r;
 end  ;


 p r o c e d u r er e m o v e __c l i c;k
 b e g i n
          s e t __p m __i n t e r r u(pktb d i n t,  o l d i n t 9 __h a n d l e)r;
          u n l o c k __d a t(ad o s m e m s e l e c t o,rs i z e o f( d o s m e m s e l e c t o)r) ;
          u n l o c k __d a t(ac l i c k p r o,c  s i z e o f(c l i c k p r o c) ) ;
          u n l o c k __c o d(e@ c l i c k e,r
                               l o n g i n t(@clicker __dummy        )
                                -   l o n g i n t(@ c l i c k e r) ) ;
          u n l o c k __c o d(e@ i n t 9 __h a n d l e,r
                               l o n g i n t(@int9 __dummy     )
                                -   l o n g i n t(@ i n t 9 __h a n d l e)r) ;
 end  ;


 v a r  ch   :   c h a r;


 b e g i n
          i n s t a l l __c l i c;k
          W r i t e l n('E n t e r|_|any |_|message    . ',
                        ' |_|P r e s|s_|r e t u r|n_|when|_|f i n i s h e'd) ;
          w h i l e ( ch  <>  #13)       do   b e g i n
                    ch   : =  r e a d k e y;  w r i t e(ch  ) ;
         end   ;
          r e m o v e __c l i c;k
_end__._________________________________________________________________________________________________________________________
 7.2.13        Software  interrupts

 Ordinarily,  a  handler  installed  with  set__ pm__ interrupt  (104)  only  services  software  inter-
 rupts  that  are  executed  in  protected  mode;  real  mode  software  interrupts  can  be  redi-
 rected by  set__ rm__ interrupt (105).  See also set__ rm__ interrupt (105), get__ rm__ interrupt (95),
 set__ pm__ interrupt (104), get__ pm__ interrupt (92), lock__ data (100), lock__ code (99), enable (88),
 disable (86), outportb (100) Executing software interrupts Simply execute a realintr() call with
 the  desired  interrupt  number  and  the  supplied  register  data  structure.  But  some  of  these
 interrupts require you to supply them a pointer to a buffer where they can store data to or
 obtain data from in memory.  These interrupts are real mode functions and so they only can
 access the first Mb of linear address space, not FPC's data segment.  For this reason FPC
 supplies a pre-initialized dos memory location within the GO32 unit.  This buffer is internally
 used for dos functions too and so it's contents may change when calling other procedures.
 It's size can be obtained with tb__ size (106) and it's linear address via transfer__ buffer (106).
 Another  way  is  to  allocate  a  completely  new  dos  memory  area  via  the  global__ dos__ alloc
 (97) function for your use and supply its real mode address.  See also:  tb__ size (106), trans-
 fer__ buffer  (106).   global__ dos__ alloc  (97),  global__ dos__ free  (98),  realintr  (101)  The  following
 examples illustrate the use of software interrupts.

________________________________________________________________________________________________________________________________
 Program       s o f t i n t;


 u s e s go32    ;
                                                                  77

 ____________________________________________________7.2.___PROTECTED_MODE_MEMORY_ORGANIZATION_____________________________________*
 *____
 v a r  r  :   t r e a l r e g;s


 b e g i n
         r . a l  : =  $01   ;
          r e a l i n t(r$21   ,  r ) ;
          W r i t e l n('DOS  |_|v' ,  r . a l, ' . ', r .ah  ,  ' |_|d e t e c t e'd) ;
_end__._________________________________________________________________________________________________________________________

________________________________________________________________________________________________________________________________
 Program       rmpm __int    ;


 u s e s  c r t,  go32   ;


 {$ASMMODE        DIRECT     }


 v a r  r  :   t r e a l r e g;s
        a x r e g :  Word    ;


        o l d i n t 2 1 h:   t s e g i n f o;
        n e w i n t 2 1 h:   t s e g i n f o;


 p r o c e d u r ei n t 2 1 h __h a n d l e;r a s s e m b l e r;
 asm
      cmpw     $0x3001     ,  % ax
      j n e  C a l l O l d
      movw     $0x3112     ,  % ax
      i r e t


 C a l l O l d:
      l j m p % c s :OLDHANDLER


OLDHANDLER        :  . l o n g  0
                      .word     0
 end  ;


 p r o c e d u r eresume     ;
 b e g i n
          W r i t e l n;
         Write    ( '--|_| p r e s s|_|any |_|key |_|to|_|resume   |_|--' ) ;  r e a d k e y;
         gotoxy     ( 1 ,  wherey     ) ;  c l r e o l;
 end  ;


 b e g i n
          c l r s c r;
          W r i t e l n('E x e c u t i n g|_|r e a|l_|mode|_|i n t e r r u p't) ;
         resume     ;
         r . ah   : =  $30   ;  r . a l : =   $01   ;    r e a l i n t(r$21   ,  r ) ;
          W r i t e l n('DOS  |_|v' ,  r . a l, ' . ', r .ah  ,  ' |_|d e t e c t e'd) ;
         resume     ;
          W r i t e l n('E x e c u t i n g|_|p r o t e c t|e_d|mode|_|i n t e r r u p't,
                        ' |_|w i t h o u|t_|o u|r_|own|_|h a n d l e'r) ;
          W r i t e l n;
         asm
               movb    $0x30    ,  % ah
               movb    $0x01    ,  % a l
               i n t  $0x21
              movw    %  ax  ,  __AXREG
         end   ;
          W r i t e l n('DOS  |_|v' ,  r . a l, ' . ', r .ah  ,  ' |_|d e t e c t e'd) ;



                                                                  78

 ____________________________________________________7.2.___PROTECTED_MODE_MEMORY_ORGANIZATION_____________________________________*
 *____
         resume     ;
          W r i t e l n('As  |_|you |_|can |_|s e e|_|t h|e_|DPMI|_|h o s t s',
                        ' |_|d e f a u l|t_|p r o t e c t|e_d|mode|_|h a n d l e'r) ;
          W r i t e l n('s i m p l y|_|r e d i r e c t|s_|i|t_|to|_|t h|e_|r e a|l_|mode|_|h a n d l e'r) ;
         resume     ;
          W r i t e l n('Now  |_|e x c h a n g i n|g_|t h|e_|p r o t e c t|e_d|mode',
                       ' i n t e r r u p t|_|w i t|h_|o u|r_|own|_|h a n d l e'r) ;
         resume     ;


          n e w i n t 2 1.ho f f s e t : =  @ i n t 2 1 h __h a n d l e;r
          n e w i n t 2 1.hsegment      : =   g e t __c s;
          g e t __p m __i n t e r r u(p$t21  ,  o l d i n t 2 1 h) ;
         asm
               movl    __OLDINT21H       ,  % eax
               movl   %  eax   , OLDHANDLER
              movw     4+  __OLDINT21H      ,  %  ax
              movw    %  ax  ,  4+ OLDHANDLER
         end   ;
          s e t __p m __i n t e r r u(p$t21  ,  n e w i n t 2 1 h) ;


          W r i t e l n('E x e c u t i n g|_|r e a|l_|mode|_|i n t e r r u p|t_|a g a i'n) ;
         resume     ;
         r . ah   : =  $30   ;  r . a l : =   $01   ;  r e a l i n t r($21  ,  r ) ;
          W r i t e l n('DOS  |_|v' ,  r . a l, ' . ', r .ah  ,  ' |_|d e t e c t e'd) ;
          W r i t e l n;
          W r i t e l n('See   , |_|i|t_|d i d'n' t|_|c h a n g e|_|i|n_|any|_|way . ') ;
         resume     ;
          W r i t e l n('Now  |_|c a l l i n|g_|p r o t e c t e|d_|mode|_|i n t e r r u p't) ;
         resume     ;
         asm
               movb    $0x30    ,  % ah
               movb    $0x01    ,  % a l
               i n t  $0x21
              movw    %  ax  ,  __AXREG
         end   ;
          W r i t e l n('DOS  |_|v' ,  l o (a x r e g) , ' . ', h i( a x r e g) ,  ' |_|d e t e c t e'd) ;
          W r i t e l n;
          W r i t e l n('Now  |_|you |_|can |_|s e e|_|t h a|t_|t h e r'e's ' ,
                        ' |_|a|_|d i s t i n c t i|o_n|b e t w e|e_n|t h|e_|two|_|ways|_|o f|_|') ;
          W r i t e l n('c a l l i n g|_|i n t e r r u p t.s. . ') ;
          s e t __p m __i n t e r r u(p$t21  ,  o l d i n t 2 1 h) ;
_end__._________________________________________________________________________________________________________________________
 7.2.14        Real  mode  callbacks

 The callback mechanism can be thought of as the converse of calling a real mode procedure
 (i.e.  interrupt), which allows your program to pass information to a real mode program, or
 obtain services from it in a manner that's transparent to the real mode program.  In order
 to make a real mode callback available,  you must first get the real mode callback address
 of your procedure and the selector and offset of a register data structure.  This real mode
 callback  address  (this  is  a  segment:offset  address)  can  be  passed  to  a  real  mode  program
 via a software interrupt,  a dos memory block or any other convenient mechanism.  When
 the real mode program calls the callback (via a far call), the DPMI host saves the registers
 contents  in  the  supplied  register  data  structure,  switches  into  protected  mode,  and  enters
 the callback routine with the following settings:


     o  interrupts disabled



                                                                  79

__________________________________________________________________7.3.___TYPES,_VARIABLES_AND_CONSTANTS____________________________*
 *___
    o  %CS:%EIP = 48 bit pointer specified in the original call to get__ rm__ callback (92)

    o  %DS:%ESI = 48 bit pointer to to real mode SS:SP

    o  %ES:%EDI = 48 bit pointer of real mode register data structure.

    o  %SS:%ESP = locked protected mode stack

    o  All other registers undefined


The  callback  procedure  can  then  extract  its  parameters  from  the  real  mode  register  data
structure  and/or  copy  parameters  from  the  real  mode  stack  to  the  protected  mode  stack.
Recall that the segment register fields of the real mode register data structure contain seg-
ment or paragraph addresses that are not valid in protected mode.  Far pointers passed in
the  real  mode  register  data  structure  must  be  translated  to  virtual  addresses  before  they
can be used with a protected mode program.  The callback procedure exits by executing an
IRET with the address of the real mode register data structure in %ES:%EDI, passing infor-
mation back to the real mode caller by modifying the contents of the real mode register data
structure and/or manipulating the contents of the real mode stack.  The callback procedure
is responsible for setting the proper address for resumption of real mode execution into the
real  mode  register  data  structure;  typically,  this  is  accomplished  by  extracting  the  return
address from the real mode stack and placing it into the %CS:%EIP fields of the real mode
register data structure.  After the IRET, the DPMI host switches the CPU back into real
mode, loads ALL registers with the contents of the real mode register data structure, and
finally  returns  control  to  the  real  mode  program.   All  variables  and  code  touched  by  the
callback procedure MUST be locked to prevent page faults.  See also:  get__ rm__ callback (92),
free__ rm__ callback (89), lock__ code (99), lock__ data (100)
7.3        Types,  Variables  and  Constants



7.3.1       Constants

Constants returned by get___run___mode


Tells you under what memory environment (e.g.  memory manager) the program currently
runs.


rm_unknown  =  0;  {  unknown  }
rm_raw        =  1;  {  raw  (without  HIMEM)  }
rm_xms        =  2;  {  XMS  (for  example  with  HIMEM,  without  EMM386)  }
rm_vcpi       =  3;  {  VCPI  (for  example  HIMEM  and  EMM386)  }
rm_dpmi       =  4;  {  DPMI  (for  example  \dos  box  or  386Max)  }


Note:   GO32V2  always  creates  DPMI  programs,  so  you  need  a  suitable  DPMI  host  like
CWSDPMI.EXE or a Windows dos box.  So you don't need to check it, these constants are
only useful in GO32V1 mode.



Processor flags constants


They are provided for a simple check with the flags identifier in the trealregs type.  To check
a single flag,  simply do an AND operation with the flag you want to check.  It's set if the
result is the same as the flag value.



                                                                 80

__________________________________________________________________7.3.___TYPES,_VARIABLES_AND_CONSTANTS____________________________*
 *___

                                          Table 7.1:  Record description


       __Record_entry__________________________________Description____________________________________________________
         available__ memory                            Largest available free block in bytes.
         available__ pages                             Maximum unlocked page allocation in pages
         available__ lockable__ pages                  Maximum locked page allocation in pages.
         linear__ space                                Linear address space size in pages.
         unlocked__ pages                              Total number of unlocked pages.
         available__ physical__ pages                  Total number of free pages.
         total__ physical__ pages                      Total number of physical pages.
         free__ linear__ space                         Free linear address space in pages.
         max__ pages__ in__ paging__ file              Size of paging file/partition in pages.

const  carryflag  =  $001;
parityflag          =  $004;
auxcarryflag       =  $010;
zeroflag             =  $040;
signflag             =  $080;
trapflag             =  $100;
interruptflag     =  $200;
directionflag     =  $400;
overflowflag       =  $800;
7.3.2       Predefined  types

type  tmeminfo  =  record
                   available_memory  :  Longint;
                   available_pages  :  Longint;
                   available_lockable_pages  :  Longint;
                   linear_space  :  Longint;
                   unlocked_pages  :  Longint;
                   available_physical_pages  :  Longint;
                   total_physical_pages  :  Longint;
                   free_linear_space  :  Longint;
                   max_pages_in_paging_file  :  Longint;
                   reserved  :  array[0..2]  of  Longint;
    end;


Holds  information  about  the  memory  allocation,  etc.     NOTE:  The  value  of  a  field  is  -1
(0ffffffffh) if the value is unknown, it's only guaranteed, that available__ memory contains a
valid value.  The size of the pages can be determined by the get__ page__ size() function.


type
trealregs  =  record
   case  Integer  of
      1:  {  32-bit  }
         (EDI,  ESI,  EBP,  Res,  EBX,  EDX,  ECX,  EAX:  Longint;
           Flags,  ES,  DS,  FS,  GS,  IP,  CS,  SP,  SS:  Word);
      2:  {  16-bit  }
         (DI,  DI2,  SI,  SI2,  BP,  BP2,  R1,  R2:  Word;
           BX,  BX2,  DX,  DX2,  CX,  CX2,  AX,  AX2:  Word);



                                                                 81

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                       3:  {  8-bit  }
                          (stuff:  array[1..4]  of  Longint;
                            BL,  BH,  BL2,  BH2,  DL,  DH,  DL2,  DH2,  CL,
                            CH,  CL2,  CH2,  AL,  AH,  AL2,  AH2:  Byte);
                       4:  {  Compat  }
                          (RealEDI,  RealESI,  RealEBP,  RealRES,  RealEBX,
                            RealEDX,  RealECX,  RealEAX:  Longint;
                            RealFlags,  RealES,  RealDS,  RealFS,  RealGS,
                            RealIP,  RealCS,  RealSP,  RealSS:  Word);
                       end;
                       registers  =  trealregs;


                 These two types contain the data structure to pass register values to a interrupt handler or
                 real mode callback.


                 type  tseginfo  =  record
                                      offset  :  Pointer;  segment  :  Word;  end;


                 This  record  is  used  to  store  a  full  48-bit  pointer.   This  may  be  either  a  protected  mode
                 selector:offset  address  or  in  real  mode  a  segment:offset  address,  depending  on  application.
                 See also:  Selectors and descriptors, dos memory access, Interrupt redirection
                 7.3.3       Variables.

                 var  dosmemselector  :  Word;


                 Selector to the dos memory.  The whole dos memory is automatically mapped to this single
                 descriptor at startup.  This selector is the recommened way to access dos memory.


                    var  int31error  :  Word;


                 This variable holds the result of a DPMI interrupt call.  Any nonzero value must be treated
                 as a critical failure.
                 7.4        Functions  and  Procedures



                 7.4.1       allocate___ldt___descriptors

Declaration:      Function  allocate__ ldt__ descriptors  (count  :    Word)  :    Word;

Description:      Allocates a number of new descriptors.  Parameters:

                 count:    specifies the number of requested unique descriptors.

                 Return  value:  The  base  selector.  Notes:  The  descriptors  allocated  must  be  initialized  by
                 the application with other function calls.  This function returns descriptors with a limit and
                 size  value  set  to  zero.   If  more  than  one  descriptor  was  requested,  the  function  returns  a
                 base selector referencing the first of a contiguous array of descriptors.  The selector values
                 for subsequent descriptors in the array can be calculated by adding the value returned by
                 the get__ next__ selector__ increment__ value (91) function.

       Errors:    Check the int31error variable.


                                                                                  82

            ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES_____________*
 *_______________
See also:    free__ ldt__ descriptor  (88),  get__ next__ selector__ increment__ value  (91),  segment__ to__ descriptor
            (103), create__ code__ segment__ alias__ descriptor (85), set__ segment__ limit (106), set__ segment__ base__ address
            (105)

           ________________________________________________________________________________________________________________________*
 *________
            Program       s e l __d e s;


            u s e s  c r t,
                    go32    ;


            c o n s t maxx     =  8 0 ;
                      maxy     =  2 5 ;
                      b y t e s p e r c e l l=  2 ;
                      s c r e e n s i z e=   maxx    *   maxy     *   b y t e s p e r c e l;l


                      l i n B 8 0 0 0=   $B800      *  1 6 ;


            type     s t r i n g 8 0=   s t r i n g[ 8 0 ] ;


            v a r
                   t e x t __s a v e:   a r r a y[ 0 . .s c r e e n s i z-e1]   of   b y t e;
                   t e x t __o l d x, t e x t __o l d y:   Word   ;


                   t e x t __s e l:   Word   ;


            p r o c e d u r es t a t u s(s   :   s t r i n g 8)0;
            b e g i n
               gotoxy     ( 1 ,  1 ) ;
               c l r e o l;
               w r i t e( s ) ;
               r e a d k e y;
            end  ;


            p r o c e d u r es e l i n f o(s e l  :  Word    ) ;
            b e g i n
            gotoxy    ( 1 ,  2 4 ) ;
            c l r e o l;
            w r i t e l n(' D e s c r i p t o|r_|b a s|e_|a d d r e s|s_|:$|_|',
                          h e x s t r(g e t __s e g m e n t __b a s e __a d d r e(ssse l) ,  8 ) ) ;
            c l r e o l;
            w r i t e(' D e s c r i p t o|r_|l i m i|t_|: |_|',
                        g e t __s e g m e n t __l i m i(ts e l) ) ;
            end  ;


            f u n c t i o nmakechar      ( ch   :   c h a r;  c o l o r  :  b y t e )  :  Word   ;
            b e g i n
                     r e s u l t: =   b y t e( ch )   or   ( c o l o r s h l  8 ) ;
            end  ;


            b e g i n
            seg __move    ( d o s m e m s e l e c t o,rl i n B 8 0 0 0,
                           get __ds   ,   l o n g i n t(@ t e x t __s a v)e,  s c r e e n s i z e) ;
            t e x t __o l d x: =  wherex     ;  t e x t __o l d y: =   wherey     ;
            s e g __f i l l w o r(dd o s m e m s e l e c t o,rl i n B 8 0 0 0,
                                   s c r e e n s i z ed i v 2 ,
                                  makechar      ( ' |_|',  B l a c k or   ( B l a c k  s h l  4 ) ) ) ;
            s t a t u s(' C r e a t i n g|_|s e l e c t o|r_|'+
                          ' '' t e x t __s e l'' |_|to|_|a|_|p a r|t_|o|f_|t e x|t_|s c r e e|n_|memory ' ) ;
            t e x t __s e l: =   a l l o c a t e __l d t __d e s c r i p t o(r1s) ;



                                                                             83

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 s e t __s e g m e n t __b a s e __a d d r e(stse x t __s e,l l i n B 8 0 0 0
                                                              +   b y t e s p e r c e l l*  maxx    *  1 ) ;
                 s e t __s e g m e n t __l i m(itte x t __s e l,
                                                s c r e e n s i z-e1-  b y t e s p e r c e l*lmaxx   * 3 ) ;
                 s e l i n f o(t e x t __s e l) ;


                 s t a t u s(' and  |_|c l e a r i n|g_|e n t i r|e_|memory |_|'+
                             ' s e l e c t e d|_|by|_|''t e x t __s e'l' |_|d e s c r i p t o'r) ;
                 s e g __f i l l w o r(dt e x t __s e l,  0 ,
                                       ( g e t __s e g m e n t __l i m i(tt e x t __s e)l+ 1 ) d i v  2 ,
                                       makechar      ( ' |_|',  L i g h t B l u es h l  4 ) ) ;


                 s t a t u s(' N o t i c e|_|t h a|t_|o n l|y_|t h|e_|memory  |_|d e s c r i b e'd+
                             ' |_|by|_|t h e|_|d e s c r i p t|o_r|c h a n g,e|d_|n o t h i n|g_|e l's)e;


                 s t a t u s('Now   |_|r e d u c i n|g_|i't's |_|l i m i t|_|and|_|b a s|e_|and|_|'+
                             ' s e t t i n g|_|i't' s|_|d e s c r i b e|d_|memory  ' ) ;
                 s e t __s e g m e n t __b a s e __a d d r e(stse x t __s e,l
                          g e t __s e g m e n t __b a s e __a d d r(etsesx t __s e l)
                         +   b y t e s p e r c e l l*  maxx   ) ;
                 s e t __s e g m e n t __l i m(itte x t __s e l,
                          g e t __s e g m e n t __l i m(itte x t __s e l)
                         -   b y t e s p e r c e l l*  maxx     *  2 ) ;
                 s e l i n f o(t e x t __s e l) ;
                 s t a t u s(' N o t i c e|_|t h a|t_|t h|e_|b a s|e_|a d d|r_|i n c r e a s|e_d|by|_|'+
                             ' one  |_|l i n e|_|but|_|t h e|_|l i m i|t_|d e c r e a s|e_d|by|_|2l|_|i n e's) ;
                 s t a t u s(' T h i s|_|s h o u l|d_|g i v|e_|you|_|t h e|_|h i n|t_|t h a|t_|t h|e_|'+
                             ' l i m i t|_|i s|_|r e l a t i|v_e|to|_|t h|e_|b a s'e) ;
                 s e g __f i l l w o r(dt e x t __s e l,  0 ,
                                       ( g e t __s e g m e n t __l i m i(tt e x t __s e)l+ 1 ) d i v  2 ,
                                       makechar      ( # 1 7 6 ,  L i g h t M a g e n t aor  Brown      s h l  4 ) ) ;


                 s t a t u s('Now   |_|l e t''s |_|g e t|_|c r a z|y_|and|_|copy |_|10 |_|l i n e's+
                             ' |_|o f|_|d a t|a_|from|_|t h e|_|p r e v i o u s l|y_|s a v|e_d|s c r e'e)n;
                 seg __move    (get __ds   ,   l o n g i n t(@ t e x t __s a v)e,
                                 t e x t __s e l, maxx    *   b y t e s p e r c e l l*  2 ,
                                maxx     *   b y t e s p e r c e l l*  1 0 ) ;


                 s t a t u s(' At |_|l a s t|_|f r e e i n|g_|t h|e_|d e s c r i p t|o_r|and|_|'+
                             ' r e s t o r i n|g_|t h|e_|o l|d_|s c r e e|n_|c o n t e n t.s. ') ;
                 s t a t u s(' I |_|hope |_|t h i s|_|l i t t l|e_|program  |_|may |_|g i v e|_|'+
                             ' you  |_|some  |_|h i n t|s_|on|_|w o r k i n|g_|w i t|h_|d e s c r i p t o'r)s;
                 f r e e __l d t __d e s c r i p t(otre x t __s e l) ;
                 seg __move    (get __ds   ,   l o n g i n t(@ t e x t __s a v)e,
                                 d o s m e m s e l e c t o,rl i n B 8 0 0 0,  s c r e e n s i z)e;
                 gotoxy    ( t e x t __o l d x, t e x t __o l d y) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.2       allocate___memory___block

Declaration:      Function  allocate__ memory__ block  (size:Longint)  :    Longint;

Description:      Allocates a block of linear memory.  Parameters:

                 size:  Size of requested linear memory block in bytes.

                 Returned values:  blockhandle - the memory handle to this memory block.  Linear address
                 of the requested memory.  Notes:  WARNING: According to my DPMI docs this function is



                                                                                  84

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 not implemented correctly.  Normally you should also get a blockhandle to this block after
                 successful  operation.   This  handle  can  then  be  used  to  free  the  memory  block  afterwards
                 or use this handle for other purposes.  Since the function isn't implemented correctly,  and
                 doesn't return a blockhandle, the block can't be deallocated and is hence unusuable !  This
                 function doesn't allocate any descriptors for this block, it's the applications resposibility to
                 allocate and initialize for accessing this memory.

       Errors:    Check the int31error variable.

     See also:    free__ memory__ block (89)
                 7.4.3       copyfromdos

Declaration:      Procedure  copyfromdos  (var  addr;  len  :    Longint);

Description:      Copies data from the pre-allocated dos memory transfer buffer to the heap.  Parameters:

                 addr:    data to copy to.

                 len:  number of bytes to copy to heap.

                 Notes:  Can only be used in conjunction with the dos memory transfer buffer.

       Errors:    Check the int31error variable.

     See also:    tb__ size (106), transfer__ buffer (106), copytodos (85)
                 7.4.4       copytodos

Declaration:      Procedure  copytodos  (var  addr;  len  :    Longint);

Description:      Copies data from heap to the pre-allocated dos memory buffer.  Parameters:

                 addr:    data to copy from.

                 len:  number of bytes to copy to dos memory buffer.

                 Notes:  This function fails if you try to copy more bytes than the transfer buffer is in size.  It
                 can only be used in conjunction with the transfer buffer.

       Errors:    Check the int31error variable.

     See also:    tb__ size (106), transfer__ buffer (106), copyfromdos (85)
                 7.4.5       create___code___segment___alias___descriptor

Declaration:      Function  create__ code__ segment__ alias__ descriptor  (seg  :    Word)  :    Word;

Description:      Creates  a  new  descriptor  that  has  the  same  base  and  limit  as  the  specified  descriptor.
                 Parameters:

                 seg:   Descriptor.

                 Return  values:  The  data  selector  (alias).  Notes:  In  effect,  the  function  returns  a  copy  of
                 the descriptor.  The descriptor alias returned by this function will not track changes to the
                 original  descriptor.  In  other  words,  if  an  alias  is  created  with  this  function,  and  the  base
                 or limit of the original segment is then changed, the two descriptors will no longer map the
                 same memory.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), set__ segment__ limit (106), set__ segment__ base__ address (105)



                                                                                  85

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.6       disable

Declaration:      Procedure  disable  ;

Description:      Disables all hardware interrupts by execution a CLI instruction.  Parameters:  None.

       Errors:    None.

     See also:    enable (88)
                 7.4.7       dosmemfillchar

Declaration:      Procedure  dosmemfillchar  (seg,  ofs  :    Word;  count  :    Longint;  c  :    char);

Description:      Sets a region of  dos memory to a specific byte value.  Parameters:

                 seg:   real mode segment.

                 ofs:  real mode offset.

                 count:    number of bytes to set.

                 c: value to set memory to.

                 Notes:  No range check is performed.

       Errors:    None.

     See also:    dosmemput (88), dosmemget (87), dosmemmove (87)dosmemmove, dosmemfillword (87), seg__ move
                 (103), seg__ fillchar (102), seg__ fillword (103)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       t e x t m e s s;


                 u s e s  c r t,  go32   ;


                 c o n s t c o l u m n s =  8 0 ;
                           rows     =  2 5 ;
                           s c r e e n s i z e=   rows   * c o l u m n s* 2 ;


                           t e x t =    ' ! |_|H e l l|o_|w o r l|d_|!;'


                 v a r  t e x t o f s :  L o n g i n t;
                        s a v e __s c r e e n:  a r r a y[ 0 . .s c r e e n s i z-e1]   of    b y t e;
                        c u r x,  c u r y  :   I n t e g e r;


                 b e g i n
                         randomize       ;
                         dosmemget       ( $B800    ,  0 ,  s a v e __s c r e e n, s c r e e n s i z e) ;
                          c u r x : =  wherex     ;  c u r y  : =  wherey     ;
                         gotoxy     ( 1 ,  1 ) ;  Write    (t e x t) ;
                          t e x t o f s: =   s c r e e n s i z e+  l e n g t h( t e x t) * 2 ;
                         dosmemmove        ( $B800    ,  0 ,  $B800    ,  t e x t o f s,  l e n g t h(t e x t) * 2 ) ;
                          d o s m e m f i l l c h a(r$B800   ,  0 ,  s c r e e n s i z e,  # 0 ) ;
                          w h i l e ( not    k e y p r e s s e)d do
                             b e g i n
                             d o s m e m f i l l c h a(r$B800   ,
                                                       t e x t o f s+   random     ( l e n g t h(t e x t) ) * 2  +  1 ,
                                                       1 ,  c h a r( random     ( 2 5 5 ) ) ) ;
                             dosmemmove       ( $B800    ,   t e x t o f s, $B800    ,
                                                random     (c o l u m n s)*2+  random     ( rows   )* c o l u m n s* 2 ,



                                                                                  86

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                                                l e n g t h(t e x t) * 2 ) ;
                                    d e l a y( 1 ) ;
                         end   ;
                         r e a d k e y;
                         r e a d k e y;
                         dosmemput       ( $B800    ,  0 ,  s a v e __s c r e e n, s c r e e n s i z e) ;
                         gotoxy     ( c u r x,  c u r y) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.8       dosmemfillword

Declaration:      Procedure  dosmemfillword  (seg,ofs  :    Word;  count  :    Longint;  w  :    Word);

Description:      Sets a region of  dos memory to a specific word value.  Parameters:

                 seg:   real mode segment.

                 ofs:  real mode offset.

                 count:    number of words to set.

                 w:  value to set memory to.

                 Notes:  No range check is performed.

       Errors:    None.

     See also:    dosmemput (88), dosmemget (87), dosmemmove (87), dosmemfillchar (86), seg__ move (103),
                 seg__ fillchar (102), seg__ fillword (103)
                 7.4.9       dosmemget

Declaration:      Procedure  dosmemget  (seg  :    Word;  ofs  :    Word;  var  data;  count  :    Longint);

Description:      Copies data from the dos memory onto the heap.  Parameters:

                 seg:   source real mode segment.

                 ofs:  source real mode offset.

                 data:    destination.

                 count:    number of bytes to copy.

                 Notes:  No range checking is performed.

       Errors:    None.

     See also:    dosmemput  (88),  dosmemmove  (87),  dosmemfillchar  (86),  dosmemfillword  (87),  seg__ move
                 (103), seg__ fillchar (102), seg__ fillword (103)


                 For an example, see global__ dos__ alloc (97).
                 7.4.10        dosmemmove

Declaration:      Procedure  dosmemmove  (sseg,  sofs,  dseg,  dofs  :    Word;  count  :    Longint);

Description:      Copies count bytes of data between two dos real mode memory locations.  Parameters:

                 sseg:   source real mode segment.

                 sofs:  source real mode offset.



                                                                                  87

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 dseg:    destination real mode segment.

                 dofs:   destination real mode offset.

                 count:    number of bytes to copy.

                 Notes:  No range check is performed in any way.

       Errors:    None.

     See also:    dosmemput (88), dosmemget (87), dosmemfillchar (86), dosmemfillword (87) seg__ move (103),
                 seg__ fillchar (102), seg__ fillword (103)


                 For an example, see seg__ fillchar (102).
                 7.4.11        dosmemput

Declaration:      Procedure  dosmemput  (seg  :    Word;  ofs  :    Word;  var  data;  count  :    Longint);

Description:      Copies heap data to dos real mode memory.  Parameters:

                 seg:   destination real mode segment.

                 ofs:  destination real mode offset.

                 data:    source.

                 count:    number of bytes to copy.

                 Notes:  No range checking is performed.

       Errors:    None.

     See also:    dosmemget  (87),  dosmemmove  (87),  dosmemfillchar  (86),  dosmemfillword  (87),  seg__ move
                 (103), seg__ fillchar (102), seg__ fillword (103)


                 For an example, see global__ dos__ alloc (97).
                 7.4.12        enable

Declaration:      Procedure  enable  ;

Description:      Enables all hardware interrupts by executing a STI instruction.  Parameters:  None.

       Errors:    None.

     See also:    disable (86)
                 7.4.13        free___ldt___descriptor

Declaration:      Function  free__ ldt__ descriptor  (des  :    Word)  :    boolean;

Description:      Frees a previously allocated descriptor.  Parameters:

                 des:   The descriptor to be freed.

                 Return  value:  True  if  successful,  False  otherwise.   Notes:  After  this  call  this  selector  is
                 invalid and must not be used for any memory operations anymore.  Each descriptor allocated
                 with  allocate__ ldt__ descriptors  (82)  must  be  freed  individually  with  this  function,  even  if  it
                 was previously allocated as a part of a contiguous array of descriptors.



                                                                                  88

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), get__ next__ selector__ increment__ value (91)


                 For an example, see allocate__ ldt__ descriptors (82).
                 7.4.14        free___memory___block

Declaration:      Function  free__ memory__ block  (blockhandle  :    Longint)  :    boolean;

Description:      Frees a previously allocated memory block.  Parameters:

                 blockhandle:  the handle to the memory area to free.

                 Return value:  True if successful, false otherwise.  Notes:  Frees memory that was previously
                 allocated  with  allocate__ memory__ block  (84)  .   This  function  doesn't  free  any  descriptors
                 mapped to this block, it's the application's responsibility.

       Errors:    Check int31error variable.

     See also:    allocate__ memory__ block (84)
                 7.4.15        free___rm___callback

Declaration:      Function  free__ rm__ callback  (var  intaddr  :    tseginfo)  :    boolean;

Description:      Releases a real mode callback address that was previously allocated with the get__ rm__ callback
                 (92) function.  Parameters:

                 intaddr:     real mode address buffer returned by get__ rm__ callback (92) .

                 Return values:  True if successful, False if not

       Errors:    Check the int31error variable.

     See also:    set__ rm__ interrupt (105), get__ rm__ callback (92)


                 For an example, see get__ rm__ callback (92).
                 7.4.16        get___cs

Declaration:      Function  get__ cs  :    Word;

Description:      Returns the cs selector.  Parameters:  None.  Return values:  The content of the cs segment
                 register.

       Errors:    None.

     See also:    get__ ds (90), get__ ss (97)


                 For an example, see set__ pm__ interrupt (104).

                                                                                  89

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.17        get___descriptor___access___rights

Declaration:      Function  get__ descriptor__ access__ rights  (d  :    Word)  :    Longint;

Description:      Gets the access rights of a descriptor.  Parameters:

                 d selector to descriptor.

                 Return value:  Access rights bit field.

       Errors:    Check the int31error variable.

     See also:    set__ descriptor__ access__ rights (104)
                 7.4.18        get___ds

Declaration:      Function  get__ ds  :    Word;

Description:      Returns the ds selector.  Parameters:  None.  Return values:  The content of the ds segment
                 register.

       Errors:    None.

     See also:    get__ cs (89), get__ ss (97)
                 7.4.19        get___linear___addr

Declaration:      Function  get__ linear__ addr  (phys__ addr  :    Longint;  size  :    Longint)  :    Longint;

Description:      Converts a physical address into a linear address.  Parameters:

                 phys___addr:       physical address of device.

                 size:  Size of region to map in bytes.

                 Return value:  Linear address that can be used to access the physical memory.  Notes:  It's
                 the applications resposibility to allocate and set up a descriptor for access to the memory.
                 This function shouldn't be used to map real mode addresses.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), set__ segment__ limit (106), set__ segment__ base__ address (105)
                 7.4.20        get___meminfo

Declaration:      Function  get__ meminfo  (var  meminfo  :    tmeminfo)  :    boolean;

Description:      Returns information about the amount of available physical memory, linear address space,
                 and disk space for page swapping.  Parameters:

                 meminfo:       buffer to fill memory information into.

                 Return  values:  Due  to  an  implementation  bug  this  function  always  returns  False,  but  it
                 always  succeeds.   Notes:   Only  the  first  field  of  the  returned  structure  is  guaranteed  to
                 contain a valid value.  Any fields that are not supported by the DPMI host will be set by the
                 host to -1  (0FFFFFFFFH) to indicate that the information is not available.  The size of the
                 pages used by the DPMI host can be obtained with the get__ page__ size (92) function.

       Errors:    Check the int31error variable.
                                                                                  90

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
     See also:    get__ page__ size (92)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       meminf    ;


                 u s e s go32    ;


                 v a r  meminfo       :  tmeminfo      ;


                 b e g i n
                 get __meminfo      ( meminfo     ) ;
                 i f  ( i n t 3 1 e r r o r<>  0)      then
                   b e g i n
                   W r i t e l n('E r r o r|_|g e t t i n|g_|DPMI |_|memory   |_|i n f o r m a t i o.n. . |_|H a l t i'n)g;
                   W r i t e l n('DPMI   |_|e r r o r|_|number  |_|: |_|', i n t 3 1 e r r o)r;
                  end
                 e l s e
                   with    meminfo       do
                      b e g i n
                      W r i t e l n(' L a r g e s t|_|a v a i l a b|l_e|f r e|e_|b l o c|k_|: |_|',
                                    a v a i l a b l e __m e m o r yd i v1 0 2 4 ,  ' |_|k b y t e's) ;
                      i f  ( a v a i l a b l e __p a g e<s>  -1)     then
                          W r i t e l n('Maximum     |_|a v a i l a b l|e_|u n l o c k e|d_|p a g|e_s|: |_|',
                                         a v a i l a b l e __p a g e)s;
                      i f  ( a v a i l a b l e __l o c k a b l e __p a g<e>s -1)     then
                          W r i t e l n('Maximum     |_|l o c k a b l|e_|a v a i l a b l|e_|p a g|e_s|: |_|',
                                         a v a i l a b l e __l o c k a b l e __p a g)e;s
                      i f  ( l i n e a r __s p a c e<>  -1)     then
                          W r i t e l n('L i n e a r|_|a d d r e s|s_|s p a c|e_|s i z|e_|: |_|',
                                        l i n e a r __s p a c*eg e t __p a g e __s i z ed i v1 0 2 4 ,
                                        ' |_|k b y t e's) ;
                      i f  ( u n l o c k e d __p a g e<s>  -1)     then
                          W r i t e l n('T o t a l|_|number   |_|o f|_|u n l o c k e|d_|p a g e|s_|:,|_|'
                                       u n l o c k e d __p a g e)s;
                      i f  ( a v a i l a b l e __p h y s i c a l __p a g<e>s -1)     then
                          W r i t e l n('T o t a l|_|number   |_|o f|_|f r e|e_|p a g e|s_|: |_|',
                                        a v a i l a b l e __p h y s i c a l __p a)g;e s
                      i f  ( t o t a l __p h y s i c a l __p a g e<s>  -1)    then
                          W r i t e l n('T o t a l|_|number   |_|o f|_|p h y s i c a|l_|p a g e|s_|:,|_|'
                                        t o t a l __p h y s i c a l __p a g)e;s
                      i f  ( f r e e __l i n e a r __s p a c<e>  -1)     then
                          W r i t e l n('F r e e|_|l i n e a|r_|a d d r e s|s_|s p a c|e_|: |_|',
                                        f r e e __l i n e a r __s p a*cgee t __p a g e __s i z ed i v 1 0 2 4 ,
                                        ' |_|k b y t e's) ;
                      i f  ( m a x __p a g e s __i n __p a g i n g __f i<l>e -1)     then
                          W r i t e l n('Maximum     |_|s i z e|_|o|f_|p a g i n|g_|f i l|e_|: |_|',
                                         m a x __p a g e s __i n __p a g i n g __f i*lgee t __p a g e __s i zdei v  1 0 2 4 ,
                                         ' |_|k b y t e's) ;
                    end   ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.21        get___next___selector___increment___value

Declaration:      Function  get__ next__ selector__ increment__ value  :    Word;

Description:      Returns the selector increment value when allocating multiple subsequent descriptors via
                 allocate__ ldt__ descriptors  (82).  Parameters:  None.  Return  value:  Selector  increment  value.
                                                                                  91

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Notes:  Because allocate__ ldt__ descriptors (82) only returns the selector for the first descriptor
                 and so the value returned by this function can be used to calculate the selectors for subsequent
                 descriptors in the array.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), free__ ldt__ descriptor (88)
                 7.4.22        get___page___size

Declaration:      Function  get__ page__ size  :    Longint;

Description:      Returns  the  size  of  a  single  memory  page.  Return  value:  Size  of  a  single  page  in  bytes.
                 Notes:  The returned size is typically 4096 bytes.

       Errors:    Check the int31error variable.

     See also:    get__ meminfo (90)


                 For an example, see get__ meminfo (90).
                 7.4.23        get___pm___interrupt

Declaration:      Function  get__ pm__ interrupt  (vector  :    byte;  var  intaddr  :    tseginfo)  :    boolean;

Description:      Returns the address of a current protected mode interrupt handler.  Parameters:

                 vector:     interrupt handler number you want the address to.

                 intaddr:     buffer to store address.

                 Return values:  True if successful, False if not.  Notes:  The returned address is a protected
                 mode selector:offset address.

       Errors:    Check the int31error variable.

     See also:    set__ pm__ interrupt (104), set__ rm__ interrupt (105), get__ rm__ interrupt (95)


                 For an example, see set__ pm__ interrupt (104).
                 7.4.24        get___rm___callback

Declaration:      Function  get__ rm__ callback  (pm__ func  :    pointer;  const  reg  :    trealregs;  var  rmcb:
                 tseginfo)  :    boolean;

Description:      Returns  a  unique  real  mode  segment:offset  address,  known  as  a  "real  mode  callback,"
                 that will transfer control from real mode to a protected mode procedure.  Parameters:

                 pm___func:      pointer to the protected mode callback function.

                 reg:   supplied registers structure.

                 rmcb:     buffer to real mode address of callback function.

                 Return  values:  True  if  successful,  otherwise  False.   Notes:  Callback  addresses  obtained
                 with this function can be passed by a protected mode program for example to an interrupt
                 handler, device driver, or TSR, so that the real mode program can call procedures within the
                 protected mode program or notify the protected mode program of an event.  The contents of
                 the supplied regs structure is not valid after function call, but only at the time of the actual
                 callback.



                                                                                  92

            ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES_____________*
 *_______________
  Errors:    Check the int31error variable.

See also:    free__ rm__ callback (89)


           ________________________________________________________________________________________________________________________*
 *________
            Program       c a l l b a c k;


            u s e s  c r t,
                    go32    ;


            c o n s t m o u s e i n t=   $33   ;


            v a r  mouse __regs            :   t r e a l r e g;s
                   m o u s e __s e g i n f o:  t s e g i n f o;


            v a r  mouse __numbuttons           :   l o n g i n t;


                   m o u s e __a c t i o n:  word   ;
                   mouse __x   ,  mouse __y     :   Word   ;
                   mouse __b     :  Word   ;


                   u s e r p r o c __i n s t a l l e:d L o n g b o o l;
                   u s e r p r o c __l e n g t h: L o n g i n t;
                   u s e r p r o c __p r o c:  p o i n t e r;


            {$ASMMODE        DIRECT     }
            p r o c e d u r ec a l l b a c k __h a n d l e;r a s s e m b l e;r
            asm
                 pushw    %  e s
                 pushw    %  ds
                 p u s h l%  e d i
                 p u s h l%  e s i
                 cmpl     $1 ,   __USERPROC__INSTALLED
                 j e  . L N o C a l l b a c k
                 p u s h a l
                 movw    % e s ,  % ax
                 movw    % ax  ,  % ds
                 movw    U__GO32__DOSMEMSELECTOR              ,  % ax
                 movw    % ax  ,  % f s
                 c a l l * __USERPROC__PROC
                 p o p a l
            . L N o C a l l b a c:k


                 p o p l %  e s i
                 p o p l %  e d i
                 popw    % ds
                 popw    % e s


                 movl    (%  e s i) ,  % eax
                 movl    % eax   ,  % e s:  4 2 ( % e d i)
                 addw     $4 ,  % e s :  4 6 ( %e d i )
                 i r e t
            end  ;


            p r o c e d u r emouse__dummy        ;  b e g i n end   ;


            p r o c e d u r et e x t u s e r p r o;c
            b e g i n
                    mouse __b     : =   mouse __regs     . bx ;



                                                                             93

___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES_________________________*
 *___
        mouse __x     : =  ( mouse __regs      . cx   s h r  3 )  +  1 ;
        mouse __y     : =  ( mouse __regs      .dx    s h r  3 )  +  1 ;
end  ;


p r o c e d u r ei n s t a l l __m o u s e(u s e r p r o c :   p o i n t e r;
                                            u s e r p r o c l e n:  l o n g i n t) ;
v a r  r  :   t r e a l r e g;s
b e g i n
        r . eax    : =  $0  ;  r e a l i n t r(m o u s e i n t, r ) ;
         i f ( r . eax   <>    $FFFF    )  then     b e g i n
              W r i t e l n('No  |_|M i r c o s o f|t_|c o m p a t i b|l_e|mouse|_|f o u n'd) ;
              Write   ( ' A |_|M i r c o s o f|t_|c o m p a t i b|l_e|mouse|_|d r i v e|r_|i's) ;
              w r i t e l n(' |_|n e c e s s a r|y_|to|_|run|_|t h i|s_|e x a m p l'e) ;
              h a l t;
        end   ;
         i f ( r . bx   =   $ f f f f)  then     mouse __numbuttons           : =  2
         e l s e mouse __numbuttons           : =   r .bx  ;
         W r i t e l n(mouse __numbuttons         ,
                       ' |_|b u t t o|n_|M i r c o s o|f_t|c o m p a t i b|l_e|mouse|_|f o u n.d' ) ;
         i f (  u s e r p r o c<>    n i l)  then     b e g i n
              u s e r p r o c __p r o c: = u s e r p r o c;
              u s e r p r o c __i n s t a l l e:d=  t r u e;
              u s e r p r o c __l e n g t:h=   u s e r p r o c l e;n
              l o c k __c o d(eu s e r p r o c __p r o,c u s e r p r o c __l e n g t)h;
        end     e l s e b e g i n
                u s e r p r o c __p r o:c=   n i l;
                u s e r p r o c __l e n g t:h=  0 ;
                u s e r p r o c __i n s t a l l e:d=  f a l s e;
        end   ;
         l o c k __d a t(amouse __x   ,   s i z e o f(mouse __x   ) ) ;
         l o c k __d a t(amouse __y   ,   s i z e o f(mouse __y   ) ) ;
         l o c k __d a t(amouse __b   ,   s i z e o f(mouse __b   ) ) ;
         l o c k __d a t(am o u s e __a c t i o,n s i z e o f( m o u s e __a c t i o)n) ;


         l o c k __d a t(au s e r p r o c __i n s t a l l,e ds i z e o f(u s e r p r o c __i n s t a l l e)d) ;
         l o c k __d a t(a@ u s e r p r o c __p r o,c s i z e o f(u s e r p r o c __p r o)c) ;


         l o c k __d a t(amouse __regs      ,  s i z e o f(mouse __regs      ) ) ;
         l o c k __d a t(am o u s e __s e g i n f,o s i z e o f(m o u s e __s e g i n f)o) ;
         l o c k __c o d(e@ c a l l b a c k __h a n d l e,r
                          l o n g i n t(@mouse__dummy        )
                           -   l o n g i n t(@ c a l l b a c k __h a n d l e)r) ;
         g e t __r m __c a l l b a c(k@ c a l l b a c k __h a n d l,emrouse __regs     ,  m o u s e __s e g i n f)o;
        r . eax    : =  $0c   ;  r .e c x  : =   $ 7 f;  r . edx   : =   l o n g i n t(m o u s e __s e g i n f.oo f f s e t) ;
        r . e s  : =  m o u s e __s e g i n f.osegment     ;
         r e a l i n t(rm o u s e i n t,  r) ;
        r . eax    : =  $01  ;
         r e a l i n t(rm o u s e i n t,  r) ;
end  ;


p r o c e d u r eremove __mouse       ;
v a r  r  :   t r e a l r e g;s
b e g i n
        r . eax    : =  $02   ;  r e a l i n t r(m o u s e i n t, r ) ;
        r . eax    : =  $0c   ;  r .e c x  : =  0 ;   r .edx    : =  0 ;   r .e s  : =  0 ;
         r e a l i n t(rm o u s e i n t,  r) ;
         f r e e __r m __c a l l b a(cmko u s e __s e g i n f)o;
         i f (  u s e r p r o c __i n s t a l l)e dthen    b e g i n
                                                                 94

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                               u n l o c k __c o d(eu s e r p r o c __p r o,c u s e r p r o c __l e n g t)h;
                               u s e r p r o c __p r o c: =  n i l;
                               u s e r p r o c __l e n g t:h=  0 ;
                               u s e r p r o c __i n s t a l l e:d=  f a l s e;
                         end   ;
                          u n l o c k __d a t(amouse __x   ,  s i z e o f(mouse __x    ) ) ;
                          u n l o c k __d a t(amouse __y   ,  s i z e o f(mouse __y    ) ) ;
                          u n l o c k __d a t(amouse __b   ,  s i z e o f(mouse __b    ) ) ;
                          u n l o c k __d a t(am o u s e __a c t i o,n s i z e o f(m o u s e __a c t i o)n) ;


                          u n l o c k __d a t(a@ u s e r p r o c __p r o,cs i z e o f( u s e r p r o c __p r o)c) ;
                          u n l o c k __d a t(au s e r p r o c __i n s t a l l,e d
                                               s i z e o f(u s e r p r o c __i n s t a l l)e)d;


                          u n l o c k __d a t(amouse __regs     ,  s i z e o f( mouse __regs     ) ) ;
                          u n l o c k __d a t(am o u s e __s e g i n f,o s i z e o f(m o u s e __s e g i n f)o) ;
                          u n l o c k __c o d(e@ c a l l b a c k __h a n d l,e r
                                               l o n g i n t(@mouse__dummy       )
                                                -   l o n g i n t(@ c a l l b a c k __h a n d l)e)r;
                          f i l l c h a(rm o u s e __s e g i n f,o s i z e o f( m o u s e __s e g i n f)o,  0 ) ;
                 end  ;



                 b e g i n
                          i n s t a l l __m o u s(e@ t e x t u s e r p r o,c 4 0 0 ) ;
                          W r i t e l n('P r e s s|_|any |_|key |_|to|_|e x i t. . . ') ;
                          w h i l e ( not    k e y p r e s s e)d do    b e g i n
                                    {   w r i t e mouse      s t a t e i n f o }
                                    gotoxy     ( 1 , wherey     ) ;
                                    w r i t e(' MouseX     |_|: |_|',mouse __x   : 2 ,
                                               ' |_|MouseY   |_|: |_|',mouse __y   : 2 ,
                                               ' |_|B u t t o n|s_|: |_|',mouse __b  : 2 ) ;
                         end   ;
                         remove __mouse       ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.25        get___rm___interrupt

Declaration:      Function  get__ rm__ interrupt  (vector  :    byte;  var  intaddr  :    tseginfo)  :    boolean;

Description:      Returns the contents of the current machine's real mode interrupt vector for the specified
                 interrupt.  Parameters:

                 vector:     interrupt vector number.

                 intaddr:     buffer to store real mode segment:offset address.

                 Return values:  True if successful,  False otherwise.  Notes:  The returned address is a real
                 mode segment address, which isn't valid in protected mode.

       Errors:    Check the int31error variable.

     See also:    set__ rm__ interrupt (105), set__ pm__ interrupt (104), get__ pm__ interrupt (92)
                 7.4.26        get___run___mode

Declaration:      Function  get__ run__ mode  :    Word;

                                                                                  95

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      Returns the current mode your application runs with.  Return values:  One of the constants
                 used by this function.

       Errors:    None.

     See also:    constants returned by get__ run__ mode (95)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       getrunmd      ;


                 u s e s go32    ;


                 b e g i n
                 {
                    d e p e n d i n g on   t h e  d e t e c t e d e n v i r o n m e n,t
                    we    s i m p l y w r i t e a n o t h e r message
                 }
                 case    ( get __run __mode     )   of
                    rm __unknown       :
                        W r i t e l n('Unknown      |_|e n v i r o n m e n|t_|f o u'n)d;
                    rm __raw           :
                        W r i t e l n('You   |_|a r e|_|c u r r e n t|l_y|r u n n i|n_g|i|n_|raw|_|mode ' ,
                                      ' |_|(w i t h o u|t_|HIMEM  ) ') ;
                    rm__xms            :
                        W r i t e l n('You   |_|a r e|_|c u r r e n t|l_y|u s i n|g_|HIMEM.SYS   |_|o n l y') ;
                    rm __vcpi          :
                        W r i t e l n('VCPI   |_|s e r v e r|_|d e t e c t e.d',
                                      ' |_|You' ' r e|_|u s i n g|_|HIMEM |_|and |_|EMM386    ') ;
                    rm __dpmi          :
                        W r i t e l n('DPMI   |_|d e t e c t e.d' ,
                                      ' |_|You' ' r e|_|u s i n g|_|a|_|DPMI|_|h o s t|_|l i k|e_|',
                                      'a |_|windows    |_|DOS |_|box |_|o r|_|CWSDPMI   ' ) ;
                 end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.27        get___segment___base___address

Declaration:      Function  get__ segment__ base__ address  (d  :    Word)  :    Longint;

Description:      Returns the 32-bit linear base address from the descriptor table for the specified segment.
                 Parameters:

                 d:  selector of the descriptor you want the base address of.

                 Return values:  Linear base address of specified descriptor.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), set__ segment__ base__ address (105), allocate__ ldt__ descriptors (82),
                 set__ segment__ limit (106), get__ segment__ limit (96)


                 For an example, see allocate__ ldt__ descriptors (82).
                 7.4.28        get___segment___limit

Declaration:      Function  get__ segment__ limit  (d  :    Word)  :    Longint;

Description:      Returns a descriptors segment limit.  Parameters:



                                                                                  96

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 d:  selector.

                 Return value:  Limit of the descriptor in bytes.

       Errors:    Returns zero if descriptor is invalid.

     See also:    allocate__ ldt__ descriptors  (82),  set__ segment__ limit  (106),  set__ segment__ base__ address  (105),
                 get__ segment__ base__ address (96),
                 7.4.29        get___ss

Declaration:      Function  get__ ss  :    Word;

Description:      Returns the ss selector.  Parameters:  None.  Return values:  The content of the ss segment
                 register.

       Errors:    None.

     See also:    get__ ds (90), get__ cs (89)
                 7.4.30        global___dos___alloc

Declaration:      Function  global__ dos__ alloc  (bytes  :    Longint)  :    Longint;

Description:      Allocates a block of  dos real mode memory.  Parameters:

                 bytes:    size of requested real mode memory.

                 Return  values:  The  low  word  of  the  returned  value  contains  the  selector  to  the  allocated
                 dos memory block, the high word the corresponding real mode segment value.  The offset
                 value is always zero.  This function allocates memory from dos memory pool, i.e.  memory
                 below the 1 MB boundary that is controlled by dos.  Such memory blocks are typically used
                 to exchange data with real mode programs, TSRs, or device drivers.  The function returns
                 both the real mode segment base address of the block and one descriptor that can be used
                 by  protected  mode  applications  to  access  the  block.   This  function  should  only  used  for
                 temporary buffers to get real mode information (e.g.  interrupts that need a data structure
                 in  ES:(E)DI),  because  every  single  block  needs  an  unique  selector.  The  returned  selector
                 should only be freed by a global__ dos__ free (98) call.

       Errors:    Check the int31error variable.

     See also:    global__ dos__ free (98)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       b u f f e r;


                 u s e s go32    ;


                 p r o c e d u r ed o s a l l o c(v a r  s e l e c t o r :  word   ;   v a r segment       :   word   ;   s i z e :*
 *   l o n g i n t) ;
                 v a r  r e s  :  l o n g i n t;
                 b e g i n
                          r e s : =   g l o b a l __d o s __a l l o(cs i z)e;
                          s e l e c t o r: =  word   ( r e s) ;
                         segment       : =   word   (r e s  s h r  1 6 ) ;
                 end  ;


                 p r o c e d u r ed o s f r e e(s e l e c t o r :  word   ) ;
                 b e g i n



                                                                                  97

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                          g l o b a l __d o s __f r e(es e l e c t o)r;
                 end  ;


                 type    VBEInfoBuf         =   r e c o r d
                                             S i g n a t u r e:   a r r a y[ 0 . . 3 ]of    c h a r;
                                             V e r s i o n :  Word   ;
                                             r e s e r v e d:   a r r a y[ 0 . . 5 0 5 ]of    b y t e;
                         end   ;


                 v a r  s e l e c t o r,
                        segment       :  Word   ;


                        r  :   t r e a l r e g;s
                        i n f o b u f :  VBEInfoBuf        ;


                 b e g i n
                          f i l l c h a(rr ,   s i z e o f(r ) ,  0 ) ;
                          f i l l c h a(ri n f o b u f,  s i z e o f(VBEInfoBuf        ) ,  0 ) ;
                          d o s a l l o(cs e l e c t o r,  segment     ,  s i z e o f(VBEInfoBuf        ) ) ;
                          i f (  i n t 3 1 e r r o<r>0)    then    b e g i n
                               W r i t e l n(' E r r o r|_|w h i l|e_|a l l o c a t i|n_g|r e a|l_|mode|_|memory  , |_|h a l t i n'*
 *g) ;
                               h a l t;
                         end   ;
                          i n f o b u f.S i g n a t u r e: =  ' VBE2   ' ;
                         dosmemput       ( segment     ,  0 ,   i n f o b u f,  s i z e o f(i n f o b u f) ) ;
                         r . ax   : =  $ 4 f 0 0;   r. e s  : =   segment     ;
                          r e a l i n t(r$10   ,  r ) ;
                         dosmemget       ( segment     ,  0 ,   i n f o b u f,  s i z e o f(i n f o b u f) ) ;
                          d o s f r e e(s e l e c t o r) ;
                          i f ( r . ax  <>    $ 4 f )  then     b e g i n
                               W r i t e l n('VBE   |_|BIOS |_|e x t e n s i o|n_|not|_|a v a i l a b l,e|_|f u n c t i o|n_|c a|l_*
 *l|f a i l e'd) ;
                               h a l t;
                         end   ;
                          i f (  i n f o b u f.s i g n a t u r[e0 ]  =   'V ' )  and    ( i n f o b u f.s i g n a t u r e[ 1 ]  = '*
 * E ')   and
                               ( i n f o b u f.s i g n a t u r[e2 ]  =   'S ' )  and    ( i n f o b u f.s i g n a t u r e[ 3 ]  = '*
 *A  ')   then     b e g i n
                               W r i t e l n('VBE   |_|v e r s i o|n_|', h i( i n f o b u f.v e r s i o n) , ' . ' ,  l o( i n f o *
 *b u f.v e r s i o n) ,  ' |_|d @
                         end   ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.31        global___dos___free

Declaration:      Function  global__ dos__ free  (selector  :Word)  :    boolean;

Description:      Frees a previously allocated dos memory block.  Parameters:

                 selector:     selector to the dos memory block.

                 Return value:  True if successful, False otherwise.  Notes:  The descriptor allocated for the
                 memory block is automatically freed and hence invalid for further use.  This function should
                 only be used for memory allocated by global__ dos__ alloc (97).

       Errors:    Check the int31error variable.

     See also:    global__ dos__ alloc (97)


                 For an example, see global__ dos__ alloc (97).


                                                                                  98

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.32        inportb

Declaration:      Function  inportb  (port  :    Word)  :    byte;

Description:      Reads 1 byte from the selected I/O port.  Parameters:

                 port:    the I/O port number which is read.

                 Return values:  Current I/O port value.

       Errors:    None.

     See also:    outportb (100), inportw (99), inportl (99)
                 7.4.33        inportl

Declaration:      Function  inportl  (port  :    Word)  :    Longint;

Description:      Reads 1 longint from the selected I/O port.  Parameters:

                 port:    the I/O port number which is read.

                 Return values:  Current I/O port value.

       Errors:    None.

     See also:    outportb (100), inportb (99), inportw (99)
                 7.4.34        inportw

Declaration:      Function  inportw  (port  :    Word)  :    Word;

Description:      Reads 1 word from the selected I/O port.  Parameters:

                 port:    the I/O port number which is read.

                 Return values:  Current I/O port value.

       Errors:    None.

     See also:    outportw (101) inportb (99), inportl (99)
                 7.4.35        lock___code

Declaration:      Function  lock__ code  (functionaddr  :    pointer;  size  :    Longint)  :    boolean;

Description:      Locks a memory range which is in the code segment selector.  Parameters:

                 functionaddr:         address of the function to be locked.

                 size:  size in bytes to be locked.

                 Return values:  True if successful, False otherwise.

       Errors:    Check the int31error variable.

     See also:    lock__ linear__ region  (100),  lock__ data  (100),  unlock__ linear__ region  (107),  unlock__ data  (107),
                 unlock__ code (106)


                 For an example, see get__ rm__ callback (92).



                                                                                  99

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.36        lock___data

Declaration:      Function  lock__ data  (var  data;  size  :    Longint)  :    boolean;

Description:      Locks a memory range which resides in the data segment selector.  Parameters:

                 data:    address of data to be locked.

                 size:  length of data to be locked.

                 Return values:  True if successful, False otherwise.

       Errors:    Check the int31error variable.

     See also:    lock__ linear__ region  (100),  lock__ code  (99),  unlock__ linear__ region  (107),  unlock__ data  (107),
                 unlock__ code (106)


                 For an example, see get__ rm__ callback (92).
                 7.4.37        lock___linear___region

Declaration:      Function  lock__ linear__ region  (linearaddr,  size  :    Longint)  :    boolean;

Description:      Locks a memory region to prevent swapping of it.  Parameters:

                 linearaddr:       the linear address of the memory are to be locked.

                 size:  size in bytes to be locked.

                 Return value:  True if successful, False otherwise.

       Errors:    Check the int31error variable.

     See also:    lock__ data (100), lock__ code (99), unlock__ linear__ region (107), unlock__ data (107), unlock__ code
                 (106)
                 7.4.38        outportb

Declaration:      Procedure  outportb  (port  :    Word;  data  :    byte);

Description:      Sends 1 byte of data to the specified I/O port.  Parameters:

                 port:    the I/O port number to send data to.

                 data:    value sent to I/O port.

                 Return values:  None.

       Errors:    None.

     See also:    inportb (99), outportl (101), outportw (101)

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       o u t p o r t;


                 u s e s  c r t,  go32   ;


                 b e g i n
                   {  t u r n  on   s p e a k e r}
                   o u t p o r t(b$61   ,  $ f f) ;
                   {  w a i t  a   l i t t l e b i t }
                   d e l a y( 5 0 ) ;
                   {  t u r n  i t  o f f  a g a i n }
                   o u t p o r t(b$61   ,  $0  ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 100

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.39        outportl

Declaration:      Procedure  outportl  (port  :    Word;  data  :    Longint);

Description:      Sends 1 longint of data to the specified I/O port.  Parameters:

                 port:    the I/O port number to send data to.

                 data:    value sent to I/O port.

                 Return values:  None.

       Errors:    None.

     See also:    inportl (99), outportw (101), outportb (100)


                 For an example, see outportb (100).
                 7.4.40        outportw

Declaration:      Procedure  outportw  (port  :    Word;  data  :    Word);

Description:      Sends 1 word of data to the specified I/O port.  Parameters:

                 port:    the I/O port number to send data to.

                 data:    value sent to I/O port.

                 Return values:  None.

       Errors:    None.

     See also:    inportw (99), outportl (101), outportb (100)


                 For an example, see outportb (100).
                 7.4.41        realintr

Declaration:      Function  realintr  (intnr:    Word;  var  regs  :    trealregs)  :    boolean;

Description:      Simulates an interrupt in real mode.  Parameters:

                 intnr:    interrupt number to issue in real mode.

                 regs:   registers data structure.

                 Return values:  The supplied registers data structure contains the values that were returned
                 by the real mode interrupt.  True if successful, False if not.  Notes:  The function transfers
                 control to the address specified by the real mode interrupt vector of intnr.  The real mode
                 handler must return by executing an IRET.

       Errors:    Check the int31error variable.

     See also:


                                                                                 101

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       f l a g s;


                 u s e s go32    ;


                 v a r  r  :   t r e a l r e g;s


                 b e g i n
                         r . ax   : =  $5300    ;
                         r . bx   : =  0 ;
                          r e a l i n t(r$15   ,  r ) ;
                          {  c h e c k  i f  c a r r y c l e a r and     w r i t e a   s u i t e d message      }
                          i f ( ( r . f l a g s and    c a r r y f l a g) = 0 )then     b e g i n
                               W r i t e l n('APM   |_|v', (r . ah   and    $ f ) ,
                                             ' . ',  ( r . a l  s h r  4 ) ,  ( r. a l  and    $ f ) ,
                                             ' |_|d e t e c t e'd) ;
                         end     e l s e
                                 W r i t e l n('APM  |_|not |_|p r e s e n't) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.42        seg___fillchar

Declaration:      Procedure  seg__ fillchar  (seg  :    Word;  ofs  :    Longint;  count  :    Longint;  c  :    char);

Description:      Sets a memory area to a specific value.  Parameters:

                 seg:   selector to memory area.

                 ofs:  offset to memory.

                 count:    number of bytes to set.

                 c: byte data which is set.

                 Return values:  None.  Notes:  No range check is done in any way.

       Errors:    None.

     See also:    seg__ move  (103),  seg__ fillword  (103),  dosmemfillchar  (86),  dosmemfillword  (87),  dosmemget
                 (87), dosmemput (88), dosmemmove (87)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       s v g a s e l;


                 u s e s go32    ;


                 v a r  v g a s e l :  Word   ;
                        r  :   t r e a l r e g;s


                 b e g i n
                    r . eax   : =   $13  ;   r e a l i n t r($10  ,  r ) ;
                    v g a s e l : =   s e g m e n t __t o __d e s c r i p t(o$rA000  ) ;
                    {   s i m p l y f i l l  t h e  s c r e e n memory      w i t h  c o l o r 1 5  }
                     s e g __f i l l c h a(rv g a s e l,  0 ,  6 4 0 0 0 ,  # 1 5 ) ;
                    r e a d l n;
                   {  back     to   t e x t mode     }
                    r . eax   : =   $3 ;
                     r e a l i n t(r$10  ,   r ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 102

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.43        seg___fillword

Declaration:      Procedure  seg__ fillword  (seg  :    Word;  ofs  :    Longint;  count  :    Longint;  w  :Word);

Description:      Sets a memory area to a specific value.  Parameters:

                 seg:   selector to memory area.

                 ofs:  offset to memory.

                 count:    number of words to set.

                 w:  word data which is set.

                 Return values:  None.  Notes:  No range check is done in any way.

       Errors:    None.

     See also:    seg__ move  (103),  seg__ fillchar  (102),  dosmemfillchar  (86),  dosmemfillword  (87),  dosmemget
                 (87), dosmemput (88), dosmemmove (87)


                 For an example, see allocate__ ldt__ descriptors (82).
                 7.4.44        segment___to___descriptor

Declaration:      Function  segment__ to__ descriptor  (seg  :    Word)  :    Word;

Description:      Maps a real mode segment (paragraph) address onto an descriptor that can be used by a
                 protected mode program to access the same memory.  Parameters:

                 seg:   the real mode segment you want the descriptor to.

                 Return values:  Descriptor to real mode segment address.  Notes:  The returned descriptors
                 limit will be set to 64 kB. Multiple calls to this function with the same segment address will
                 return the same selector.  Descriptors created by this function can never be modified or freed.
                 Programs which need to examine various real mode addresses using the same selector should
                 use the function allocate__ ldt__ descriptors (82) and change the base address as necessary.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), free__ ldt__ descriptor (88), set__ segment__ base__ address (105)


                 For an example, see seg__ fillchar (102).
                 7.4.45        seg___move

Declaration:      Procedure  seg__ move  (sseg  :    Word;  source  :    Longint;  dseg  :    Word;  dest  :    Longint;
                 count  :    Longint);

Description:      Copies data between two memory locations.  Parameters:

                 sseg:   source selector.

                 source:     source offset.

                 dseg:    destination selector.

                 dest:   destination offset.

                 count:    size in bytes to copy.

                 Return values:  None.  Notes:  Overlapping is only checked if the source selector is equal to
                 the destination selector.  No range check is done.



                                                                                 103

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    None.

     See also:    seg__ fillchar  (102),  seg__ fillword (103),  dosmemfillchar  (86),  dosmemfillword (87),  dosmemget
                 (87), dosmemput (88), dosmemmove (87)


                 For an example, see allocate__ ldt__ descriptors (82).
                 7.4.46        set___descriptor___access___rights

Declaration:      Function  set__ descriptor__ access__ rights  (d  :    Word;  w  :    Word)  :    Longint;

Description:      Sets the access rights of a descriptor.  Parameters:

                 d:  selector.

                 w:  new descriptor access rights.

                 Return values:  This function doesn't return anything useful.

       Errors:    Check the int31error variable.

     See also:    get__ descriptor__ access__ rights (90)
                 7.4.47        set___pm___interrupt

Declaration:      Function  set__ pm__ interrupt  (vector  :    byte;  const  intaddr  :    tseginfo)  :    boolean;

Description:      Sets the address of the protected mode handler for an interrupt.  Parameters:

                 vector:     number of protected mode interrupt to set.

                 intaddr:     selector:offset address to the interrupt vector.

                 Return values:  True if successful, False otherwise.  Notes:  The address supplied must be a
                 valid selector:offset protected mode address.

       Errors:    Check the int31error variable.

     See also:    get__ pm__ interrupt (92), set__ rm__ interrupt (105), get__ rm__ interrupt (95)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       int __pm  ;


                 u s e s  c r t,  go32   ;


                 c o n s t i n t 1 c =   $1c  ;


                 v a r  o l d i n t 1 c:   t s e g i n f o;
                        n e w i n t 1 c:   t s e g i n f o;
                        i n t 1 c __c o u n t e r:  L o n g i n t;


                 {$ASMMODE        DIRECT     }
                 p r o c e d u r ei n t 1 c __h a n d l e;r a s s e m b l e r;
                 asm
                      c l i
                      pushw    %  ds
                      pushw    %  ax
                      movw    % c s :INT1C__DS      ,  % ax
                      movw    % ax  ,  % ds
                      i n c l  __INT1C__COUNTER



                                                                                 104

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                      popw    % ax
                      popw    % ds
                      s t i
                      i r e t
                 INT1C__DS     :  . word    0
                 end  ;


                 v a r  i  :   L o n g i n t;


                 b e g i n
                          n e w i n t 1.co f f s e t : =   @ i n t 1 c __h a n d l e;r
                          n e w i n t 1.csegment       : =  g e t __c s;
                          g e t __p m __i n t e r r u(pitn t 1 c,   o l d i n t 1)c;
                         asm
                              movw    %  ds  ,  % ax
                              movw    %  ax  ,  INT1C__DS
                         end   ;
                          W r i t e l n('--|_|P r e s s|_|any |_|key |_|to|_|e x i t|_|--') ;
                          s e t __p m __i n t e r r u(pitn t 1 c,  n e w i n t 1 c) ;
                          w h i l e ( not    k e y p r e s s e)d do    b e g i n
                                    gotoxy     ( 1 , wherey     ) ;
                                    w r i t e(' Number     |_|o f|_|i n t e r r u p|t_s|o c c u r|e_d|: |_|',
                                               i n t 1 c __c o u n t e)r;
                         end   ;
                          s e t __p m __i n t e r r u(pitn t 1 c,   o l d i n t 1)c;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 7.4.48        set___rm___interrupt

Declaration:      Function  set__ rm__ interrupt  (vector  :    byte;  const  intaddr  :    tseginfo)  :    boolean;

Description:      Sets a real mode interrupt handler.  Parameters:

                 vector:     the interrupt vector number to set.

                 intaddr:     address of new interrupt vector.

                 Return values:  True if successful, otherwise False.  Notes:  The address supplied MUST be a
                 real mode segment address, not a selector:offset address.  So the interrupt handler must
                 either reside in dos memory (below 1 Mb boundary) or the application must allocate a real
                 mode callback address with get__ rm__ callback (92).

       Errors:    Check the int31error variable.

     See also:    get__ rm__ interrupt  (95),  set__ pm__ interrupt  (104),  get__ pm__ interrupt  (92),  get__ rm__ callback
                 (92)
                 7.4.49        set___segment___base___address

Declaration:      Function  set__ segment__ base__ address  (d  :    Word;  s  :    Longint)  :    boolean;

Description:      Sets the 32-bit linear base address of a descriptor.  Parameters:

                 d:  selector.

                 s: new base address of the descriptor.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), get__ segment__ base__ address (96), allocate__ ldt__ descriptors (82),
                 set__ segment__ limit (106), get__ segment__ base__ address (96), get__ segment__ limit (96)



                                                                                 105

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.50        set___segment___limit

Declaration:      Function  set__ segment__ limit  (d  :    Word;  s  :    Longint)  :    boolean;

Description:      Sets the limit of a descriptor.  Parameters:

                 d:  selector.

                 s: new limit of the descriptor.

                 Return values:  Returns True if successful, else False.  Notes:  The new limit specified must
                 be the byte length of the segment - 1.  Segment limits bigger than or equal to 1MB must be
                 page aligned, they must have the lower 12 bits set.

       Errors:    Check the int31error variable.

     See also:    allocate__ ldt__ descriptors (82), set__ segment__ base__ address (105), get__ segment__ limit (96), set__ segmen*
 *t__ limit
                 (106)


                 For an example, see allocate__ ldt__ descriptors (82).
                 7.4.51        tb___size

Declaration:      Function  tb__ size  :    Longint;

Description:      Returns the size of the pre-allocated dos memory buffer.  Parameters:  None.  Return values:
                 The size of the pre-allocated dos memory buffer.  Notes:  This block always seems to be 16k
                 in size, but don't rely on this.

       Errors:    None.

     See also:    transfer__ buffer (106), copyfromdos (85) copytodos (85)
                 7.4.52        transfer___buffer

Declaration:      Function  transfer__ buffer  :    Longint;

Description:      transfer__ buffer returns the offset of the transfer buffer.

       Errors:    None.

     See also:    tb__ size (106)
                 7.4.53        unlock___code

Declaration:      Function  unlock__ code  (functionaddr  :    pointer;  size  :    Longint)  :    boolean;

Description:      Unlocks a memory range which resides in the code segment selector.  Parameters:

                 functionaddr:         address of function to be unlocked.

                 size:  size bytes to be unlocked.

                 Return value:  True if successful, False otherwise.

       Errors:    Check the int31error variable.

     See also:    unlock__ linear__ region  (107),  unlock__ data  (107),  lock__ linear__ region  (100),  lock__ data  (100),
                 lock__ code (99)


                 For an example, see get__ rm__ callback (92).



                                                                                 106

                 ___________________________________________________________________________7.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 7.4.54        unlock___data

Declaration:      Function  unlock__ data  (var  data;  size  :    Longint)  :    boolean;

Description:      Unlocks a memory range which resides in the data segment selector.  Paramters:

                 data:    address of memory to be unlocked.

                 size:  size bytes to be unlocked.

                 Return values:  True if successful, False otherwise.

       Errors:    Check the int31error variable.

     See also:    unlock__ linear__ region  (107),  unlock__ code  (106),  lock__ linear__ region  (100),  lock__ data  (100),
                 lock__ code (99)


                 For an example, see get__ rm__ callback (92).
                 7.4.55        unlock___linear___region

Declaration:      Function  unlock__ linear__ region  (linearaddr,  size  :    Longint)  :    boolean;

Description:      Unlocks  a  previously  locked  linear  region  range  to  allow  it  to  be  swapped  out  again  if
                 needed.  Parameters:

                 linearaddr:       linear address of the memory to be unlocked.

                 size:  size bytes to be unlocked.

                 Return values:  True if successful, False otherwise.

       Errors:    Check the int31error variable.

     See also:    unlock__ data (107), unlock__ code (106), lock__ linear__ region (100), lock__ data (100), lock__ code
                 (99)


                                                                                 107


Chapter   8


The   GRAPH   unit.



This document describes the GRAPH unit for Free Pascal, for all platforms.  The unit was first
written for dos by Florian kl"ampfl, but was later completely rewritten by Carl-Eric Codere
to be completely portable.

This chapter is divided in 4 sections.


    o  The first section gives an introduction to the graph unit.

    o  The second section lists the pre-defined constants, types and variables.

    o  The second section describes the functions which appear in the interface part of the
       GRAPH unit.

    o  The last part describes some system-specific issues.
8.1        Introduction



8.1.1       Requirements

The unit Graph exports functions and procedures for graphical output.  It requires at least a
VGA-compatible Card or a VGA-Card with software-driver (min.  512Kb video memory).
8.1.2       A  word  about  mode  selection

The  graph  unit  was  implemented  for  compatibility  with  the  old  Turbo  Pascal  graph  unit.
For this reason, the mode constants as they were defined in the Turbo Pascal graph unit are
retained.

However, since


   1.  Video cards have evolved very much

   2.  Free Pascal runs on multiple platforms


it was decided to implement new mode and graphic driver constants, which are more inde-
pendent of the specific platform the program runs on.

In this section we give a short explanation of the new mode system.  the following drivers
were defined:

                                                            108

 ____________________________________________________________________________________________________8.1.___INTRODUCTION___________*
 *____
 D1bit  =  11;
 D2bit  =  12;
 D4bit  =  13;
 D6bit  =  14;    {  64  colors  Half-brite  mode  -  Amiga  }
 D8bit  =  15;
 D12bit  =  16;  {  4096  color  modes  HAM  mode  -  Amiga  }
 D15bit  =  17;
 D16bit  =  18;
 D24bit  =  19;  {  not  yet  supported  }
 D32bit  =  20;  {  not  yet  supported  }
 D64bit  =  21;  {  not  yet  supported  }


 lowNewDriver  =  11;
 highNewDriver  =  21;


 Each of these drivers specifies a desired color-depth.

 The following modes have been defined:


 detectMode  =  30000;
 m320x200  =  30001;
 m320x256  =  30002;  {  amiga  resolution  (PAL)  }
 m320x400  =  30003;  {  amiga/atari  resolution  }
 m512x384  =  30004;  {  mac  resolution  }
 m640x200  =  30005;  {  vga  resolution  }
 m640x256  =  30006;  {  amiga  resolution  (PAL)  }
 m640x350  =  30007;  {  vga  resolution  }
 m640x400  =  30008;
 m640x480  =  30009;
 m800x600  =  30010;
 m832x624  =  30011;  {  mac  resolution  }
 m1024x768  =  30012;
 m1280x1024  =  30013;
 m1600x1200  =  30014;
 m2048x1536  =  30015;


 lowNewMode  =  30001;
 highNewMode  =  30015;


 These  modes  start  at  30000  because  Borland  specified  that  the  mode  number  should  be
 ascending with increasing X resolution, and the new constants shouldn't interfere with the
 old ones.

 The above constants can be used to set a certain color depth and resultion, as demonstrated
 in the following example:

 Listing:  graphex/inigraph1.pp
________________________________________________________________________________________________________________________________
 Program       i n i g r a p h;1


 {  Program       to    d e m o n s t r a t es t a t i c g r a p h i c smode     s e l e c t i o n}


 u s e s  g r a p h;



 c o n s t
    T h e L i n e =   'We  |_|a r e|_|now|_|i n|_|6 4 0x|_||_|4 8x0||_|_|2 5c6o|_|l o r!s'+



                                                                 109

 ____________________________________________________________________________________________________8.1.___INTRODUCTION___________*
 *____
                      ' |_|(p r e s s|_|<R e t u r>n|_|to|_|c o n t i n u)e';


 v a r
    gd  ,  gm  ,  l o ,  h i ,  e r r o r,tw  , th  :  i n t e g e r;
    f o u n d:   b o o l e a n;


 b e g i n
    {  We    want     an   8   b i t mode     }
    gd   : =   D 8 b i t;
    gm   : =   m640x480      ;
    i n i t g r a p h(gd , gm , ' ' ) ;
    {   Make     s u r e you    a l w a y s c h e c k  g r a p h r e s u l!t }
    e r r o r : =   g r a p h R e s u l;t
    i f  ( e r r o r <>    grOk   )  Then
        b e g i n
        w r i t e l n(' 6 4 0x 4 8 0 x 2 5 6|_|i|s_|not|_|s u p p o r t e!d') ;
        h a l t( 1 )
        end  ;
    {  We    a r e  now    i n  6 4 0x 4 8 0 x 2 5 6 }
    s e t C o l o r(cyan   ) ;
    r e c t a n g l e( 0 , 0 ,getmaxx    , getmaxy     ) ;
    {   W r i t e a   n i c e message       i n   t h e  c e n t e r o f  t h e  s c r e e n }
    s e t T e x t S t y l(ed e f a u l t F o n,th o r i z D i r, 1 ) ;
    tw  := TextWidth       ( T h e L i n e) ;
    th  := T e x t H e i g h t(T h e L i n e) ;
    outTextXY       ( (getMaxX       -  TW  )   d i v  2 ,
                      (getMaxY       -  TH  )   d i v  2 ,T h e L i n e) ;
    {   Wait     f o r  r e t u r n}
    r e a d l n;
    {   Back    to    t e x t mode     }
    c l o s e g r a p h;
_end__._________________________________________________________________________________________________________________________

 If other modes than the ones above are supported by the graphics card, you will not be able
 to select them with this mechanism.

 For this reason, there is also a 'dynamic' mode number, which is assigned at run-time.  This
 number  increases  with  increasing  X  resolution.  It  can  be  queried  with  the  getmoderange
 call.  This call will return the range of modes which are valid for a certain graphics driver.
 The  numbers  are  guaranteed  to  be  consecutive,  and  can  be  used  to  search  for  a  certain
 resolution, as in the following example:

 Listing:  graphex/inigraph2.pp

________________________________________________________________________________________________________________________________
 Program       i n i g r a p h;2


 {  Program       to    d e m o n s t r a t edynamic      g r a p h i c s mode     s e l e c t i o n}


 u s e s  g r a p h;


 c o n s t
    T h e L i n e =   'We  |_|a r e|_|now|_|i n|_|6 4 0x|_||_|4 8x0||_|_|2 5c6o|_|l o r!s'+
                      ' |_|(p r e s s|_|<R e t u r>n|_|to|_|c o n t i n u)e';


 v a r
    th  ,tw  , gd ,  gm  ,   l o,   h i,   e r r o r:  i n t e g e r;
    f o u n d:   b o o l e a n;


 b e g i n



                                                                 110

 ____________________________________________________________________________________________________8.1.___INTRODUCTION___________*
 *____
    {  We    want     an   8   b i t mode     }
    gd   : =   D 8 b i t;
    {   Get    a l l  a v a i l a b l er e s o l u t i o n sf o r  t h i s  b i t d e p t h}
    g e t m o d e r a n g(egd , l o ,h i ) ;
    {   I f  t h e  h i g h e s t a v a i l a b l emode     number      i s  -1,
        no   r e s o l u t i o n sa r e  s u p p o r t e df o r  t h i s  b i t d e p t h  }
    i f   h i =  -1    then
        b e g i n
        w r i t e l n('no  |_|8 |_|b i|t_|modes |_|s u p p o r t e!d') ;
        h a l t
        end  ;
    f o u n d : =   f a l s e;
    {   S e a r c h a l l  r e s o l u t i o n sf o r 6 4 0 x480    }
    f o r  gm   : =   l o  to   h i  do
        b e g i n
        i n i t g r a p(hgd  ,gm  , ' ') ;
        {  Make     s u r e  you    a l w a y s c h e c k g r a p h r e s u l t!  }
        e r r o r : =   g r a p h R e s u l;t
        i f  ( e r r o r =   grOk   )  and
             ( getmaxx      =  6 3 9 )   and    ( getmaxy      =  4 7 9 )   then
           b e g i n
           f o u n d : =   t r u e;
           break    ;
           end   ;
        end  ;
    i f  not    f o u n d  then
        b e g i n
        w r i t e l n(' 6 4 0x 4 8 0 x 2 5 6|_|i|s_|not|_|s u p p o r t e!d') ;
        h a l t( 1 )
        end  ;
    {  We    a r e  now    i n  6 4 0x 4 8 0 x 2 5 6 }
    s e t C o l o r(cyan   ) ;
    r e c t a n g l e( 0 , 0 ,getmaxx    , getmaxy     ) ;
    {   W r i t e a   n i c e message       i n   t h e  c e n t e r o f  t h e  s c r e e n }
    s e t T e x t S t y l(ed e f a u l t F o n,th o r i z D i r, 1 ) ;
    TW  := TextWidth       ( T h e L i n e) ;
    TH  := T e x t H e i g h t(T h e L i n e) ;
    outTextXY       ( (getMaxX       -  TW  )   d i v  2 ,
                      (getMaxY       -  TH  )   d i v  2 ,T h e L i n e) ;
    {   Wait     f o r  r e t u r n}
    r e a d l n;
    {   Back    to    t e x t mode     }
    c l o s e g r a p h;
_end__._________________________________________________________________________________________________________________________

 Thus, the getmoderange function can be used to detect all available modes and drivers, as
 in the following example:

 Listing:  graphex/modrange.pp

________________________________________________________________________________________________________________________________
 Program       GetModeRange __Example             ;


 {  T h i s  program       d e m o n s t r a t e show    to   f i n d  a l l  a v a i l a b l eg r a p h modes     }


 u s e s  g r a p h;


 c o n s t
    {   C u r r e n t l y, o n l y  4 ,  8 ,  1 5  and    1 6   b i t modes      a r e  s u p p o r t e d
        but    t h i s may      c h a n g e i n   t h e  f u t u r e}



                                                                 111

 ____________________________________________________________________________________________________8.1.___INTRODUCTION___________*
 *____
    gdnames      :  a r r a y[D 4 b i t. . D 1 6 b i t]  of   s t r i n g[ 6 ]  =
        ( ' 4 |_|b i't, ' 6 |_|b i't,' 8 |_|b i t',' 1 2 |_|b i t',' 1 5 |_|b i't, ' 1 6 |_|b i't) ;


 v a r
    t :   t e x t;
    gd  ,  c ,  low   ,  h i g h,   r e s:   i n t e g e r;
 b e g i n
    a s s i g n(t , ' modes   . t x t' ) ;
    r e w r i t e(t ) ;
    c l o s e( t ) ;
    f o r  gd   : =   D 4 b i t to   D 1 6 b i t do
        b e g i n
        {  Get    t h e  a v a i l a b l emode     numbers       f o r  t h i s  d r i v e r }
        getModeRange         (gd  , low  , h i g h) ;
        append    ( t ) ;
        w r i t e(t , gdnames     [ gd ] ) ;
        W r i t e l n(t, ' : |_|low |_|modenr   |_|= |_|',low , ' , |_|h i g|h_|modenr  |_|= |_|',h i g h) ;
        c l o s e(t ) ;
        {  I f   h i g h i s  -1,
             no   r e s o l u t i o n sa r e  s u p p o r t e d f o r  t h i s b i t d e p t h}
        i f  h i g h =  -1    then
           b e g i n
           append     (t ) ;
           w r i t e l n(t , ' |_||_|No|_|modes |_|s u p p o r t e!d') ;
           w r i t e l n(t ) ;
           c l o s e( t ) ;
           end
        e l s e
           {   E n t e r a l l  s u p p o r t e d r e s o l u t i o n sf o r  t h i s b i t d e p t h
               and    w r i t e t h e i r  c h a r a c t e r i s t i ctso   t h e  f i l e }
           f o r  c  : =   low    to   h i g h  do
               b e g i n
               append    ( t ) ;
               w r i t e l n(t, ' |_||_|t e s t i n|g_|mode|_|nr|_|',c ) ;
               c l o s e(t ) ;
               i n i t g r a p(hgd  ,c , ' ') ;
               r e s : =   g r a p h r e s u l;t
               append    ( t ) ;
               {  An    e r r o r o c c u r r e dwhen     e n t e r i n g t h e  mode   ?  }
               i f  r e s <>    g r o k  then
                  w r i t e l n(t , g r a p h e r r o r m s(gr e s) )
               e l s e
                  b e g i n
                  w r i t e( t, ' maxx   : |_|',getmaxx     , ' , |_|maxy : |_|',getmaxy     ) ;
                  W r i t e l n(t , ' , |_|m a x c o l o:r|_|',g e t m a x c o l o)r;
                  c l o s e g r a p h;
                  end  ;
               w r i t e l n(t ) ;
               c l o s e(t ) ;
               end  ;
        append    ( t ) ;
        w r i t e l n(t ) ;
        c l o s e(t ) ;
        end  ;
_end__._________________________________________________________________________________________________________________________

                                                                 112

__________________________________________________________________8.2.___CONSTANTS,_TYPES_AND_VARIABLES____________________________*
 *___
8.2        Constants,  Types  and  Variables



8.2.1       Types

ArcCoordsType  =  record
 X,Y,Xstart,Ystart,Xend,Yend  :  Integer;
end;
FillPatternType  =  Array  [1..8]  of  Byte;
FillSettingsType  =  Record
 Pattern,Color  :  Word
end;
LineSettingsType  =  Record
   LineStyle,Pattern,  Width  :  Word;
end;
PaletteType  =  Record
 Size  :  Byte;
 Colors  :  array[0..MAxColor]  of  shortint;
end;
PointType  =  Record
   X,Y  :  Integer;
end;
TextSettingsType  =  Record
 Font,Direction,  CharSize,  Horiz,  Vert  :  Word
end;
ViewPortType  =  Record
   X1,Y1,X2,Y2  :  Integer;
   Clip  :  Boolean
end;
8.3        Function  list  by  category


What follows is a listing of the available functions, grouped by category.  For each function
there is a reference to the page where you can find the function.
8.3.1       Initialization

Initialization of the graphics screen.


Name_______________________________________________Description_________________________________________________Page___________

  ClearDevice                      Empty the graphics screen                                                 117

  CloseGraph                       Finish drawing session, return to text mode                         117

  DetectGraph                      Detect graphical modes                                                     117

  GetAspectRatio                   Get aspect ratio of screen                                                  119

  GetModeRange                     Get range of valid modes for current driver                          121

  GraphDefaults                    Set defaults                                                                     123

  GetDriverName                    Return name of graphical driver                                         119

  GetGraphMode                     Return current or last used graphics mode                           120

  GetMaxMode                       Get maximum mode for current driver                                 121

  GetModeName                      Get name of current mode                                                 121



                                                                113

___________________________________________________________________________8.3.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
  GraphErrorMsg                    String representation of graphical error                                123

  GraphResult                      Result of last drawing operation                                         123

  InitGraph                        Initialize graphics drivers                                                   124

  InstallUserDriver                Install a new driver                                                           124

  RegisterBGIDriver                Register a new driver                                                        127

  RestoreCRTMode                   Go back to text mode                                                       127

  SetGraphBufSize                  Set buffer size for graphical operations                                 129

  SetGraphMode                     Set graphical mode                                                           130
8.3.2       screen  management

General drawing screen management functions.


Name_______________________________________________Description_________________________________________________Page___________

  ClearViewPort                    Clear the current viewport                                                 117

  GetImage                         Copy image from screen to memory                                    120

  GetMaxX                          Get maximum X coordinate                                               121

  GetMaxY                          Get maximum Y coordinate                                               121

  GetX                             Get current X position                                                      122

  GetY                             Get current Y position                                                      122

  ImageSize                        Get size of selected image                                                  123

  GetViewSettings                  Get current viewport settings                                             122

  PutImage                         Copy image from memory to screen                                    126

  SetActivePage                    Set active video page                                                        128

  SetAspectRatio                   Set aspect ratio for drawing routines                                   128

  SetViewPort                      Set current viewport                                                         132

  SetVisualPage                    Set visual page                                                                 132

  SetWriteMode                     Set write mode for screen operations                                   132
8.3.3       Color  management

All functions related to color management.


Name_______________________________________________Description_________________________________________________Page___________

  GetBkColor                       Get current background color                                             119

  GetColor                         Get current foreground color                                              119

  GetDefaultPalette                Get default palette entries                                                 119

  GetMaxColor                      Get maximum valid color                                                   120

  GetPaletteSize                   Get size of palette for current mode                                    122

  GetPixel                         Get color of selected pixel                                                  122

  GetPalette                       Get palette entry                                                              121

  SetAllPallette                   Set all colors in palette                                                      128



                                                                114

___________________________________________________________________________8.3.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
  SetBkColor                       Set background color                                                         128

  SetColor                         Set foreground color                                                          129

  SetPalette                       Set palette entry                                                              130

  SetRGBPalette                    Set palette entry with RGB values                                      130
8.3.4       Drawing  primitives

Functions for simple drawing.


Name_______________________________________________Description_________________________________________________Page___________

  Arc                              Draw an arc                                                                     116

  Circle                           Draw a complete circle                                                      117

  DrawPoly                         Draw a polygone with N points                                          118

  Ellipse                          Draw an ellipse                                                                118

  GetArcCoords                     Get arc coordinates                                                           119

  GetLineSettings                  Get current line drawing settings                                        120

  Line                             Draw line between 2 points                                                125

  LineRel                          Draw line relative to current position                                  125

  LineTo                           Draw line from current position to absolute position              125

  MoveRel                          Move cursor relative to current position                               125

  MoveTo                           Move cursor to absolute position                                         125

  PieSlice                         Draw a pie slice                                                                126

  PutPixel                         Draw 1 pixel                                                                    127

  Rectangle                        Draw a non-filled rectangle                                                127

  Sector                           Draw a sector                                                                  128

  SetLineStyle                     Set current line drawing style                                             130
8.3.5       Filled  drawings

Functions for drawing filled regions.


Name_______________________________________________Description_________________________________________________Page___________

  Bar3D                            Draw a filled 3D-style bar                                                  116

  Bar                              Draw a filled rectangle                                                      116

  FloodFill                        Fill starting from coordinate                                              118

  FillEllipse                      Draw a filled ellipse                                                          118

  FillPoly                         Draw a filled polygone                                                       118

  GetFillPattern                   Get current fill pattern                                                      120

  GetFillSettings                  Get current fill settings                                                     120

  SetFillPattern                   Set current fill pattern                                                       129

  SetFillStyle                     Set current fill settings                                                      129


                                                                115

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.3.6       Text  and  font  handling

                 Functions to set texts on the screen.


                 Name_______________________________________________Description_________________________________________________Pag*
 *e___________

                   GetTextSettings                  Get current text settings                                                   122

                   InstallUserFont                  Install a new font                                                             *
 *124

                   OutText                          Write text at current cursor position                                   126

                   OutTextXY                        Write text at coordinates X,Y                                            126

                   RegisterBGIFont                  Register a new font                                                           1*
 *27

                   SetTextJustify                   Set text justification                                                         *
 *131

                   SetTextStyle                     Set text style                                                                 *
 *  131

                   SetUserCharSize                  Set text size                                                                  *
 *   131

                   TextHeight                       Calculate height of text                                                     132

                   TextWidth                        Calculate width of text                                                      132
                 8.4        Functions  and  procedures



                 8.4.1       Arc

Declaration:      Procedure  Arc  (X,Y  :  Integer;  start,stop,  radius  :    Word);

Description:      Arc draws part of a circle with center at (X,Y), radius radius, starting from angle start,
                 stopping at angle stop.  These angles are measured counterclockwise.

       Errors:    None.

     See also:    Circle (117),Ellipse (118) GetArcCoords (119),PieSlice (126), Sector (128)
                 8.4.2       Bar

Declaration:      Procedure  Bar  (X1,Y1,X2,Y2  :    Integer);

Description:      Draws a rectangle with corners at (X1,Y1) and (X2,Y2) and fills it with the current color
                 and fill-style.

       Errors:    None.

     See also:    Bar3D (116), Rectangle (127)
                 8.4.3       Bar3D

Declaration:      Procedure  Bar3D  (X1,Y1,X2,Y2  :    Integer;  depth  :    Word;  Top  :    Boolean);

Description:      Draws  a  3-dimensional  Bar  with  corners  at  (X1,Y1)  and  (X2,Y2)  and  fills  it  with  the
                 current color and fill-style.  Depth specifies the number of pixels used to show the depth of
                 the bar.  If  Top is true; then a 3-dimensional top is drawn.

       Errors:    None.

     See also:    Bar (116), Rectangle (127)
                                                                                 116

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.4       Circle

Declaration:      Procedure  Circle  (X,Y  :  Integer;  Radius  :    Word);

Description:      Circle draws part of a circle with center at (X,Y), radius radius.

       Errors:    None.

     See also:    Ellipse (118),Arc (116) GetArcCoords (119),PieSlice (126), Sector (128)
                 8.4.5       ClearDevice

Declaration:      Procedure  ClearDevice  ;

Description:      Clears  the  graphical  screen  (with  the  current  background  color),  and  sets  the  pointer  at
                 (0,0)

       Errors:    None.

     See also:    ClearViewPort (117), SetBkColor (128)
                 8.4.6       ClearViewPort

Declaration:      Procedure  ClearViewPort  ;

Description:      Clears  the  current  viewport.  The  current  background  color  is  used  as  filling  color.  The
                 pointer is set at (0,0)

       Errors:    None.

     See also:    ClearDevice (117),SetViewPort (132), SetBkColor (128)
                 8.4.7       CloseGraph

Declaration:      Procedure  CloseGraph  ;

Description:      Closes  the  graphical  system,  and  restores  the  screen  modus  which  was  active  before  the
                 graphical modus was activated.

       Errors:    None.

     See also:    InitGraph (124)
                 8.4.8       DetectGraph

Declaration:      Procedure  DetectGraph  (Var  Driver,  Modus  :    Integer);

Description:      Checks the hardware in the PC and determines the driver and screen-modus to be used.
                 These are returned in Driver and Modus, and can be fed to InitGraph.  See the InitGraph
                 for a list of drivers and modi.

       Errors:    None.

     See also:    InitGraph (124)

                                                                                 117

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.9       DrawPoly

Declaration:      Procedure  DrawPoly  (NumberOfPoints  :    Word;  Var  PolyPoints;

Description:      Draws  a  polygone  with  NumberOfPoints  corner  points,  using  the  current  color  and  line-
                 style.  PolyPoints is an array of type PointType.

       Errors:    None.

     See also:    Bar (116), seepBar3D, Rectangle (127)
                 8.4.10        Ellipse

Declaration:      Procedure  Ellipse  (X,Y  :  Integer;  Start,Stop,XRadius,YRadius  :    Word);

Description:      Ellipse  draws  part  of  an  ellipse  with  center  at  (X,Y).  XRadius  and  Yradius  are  the
                 horizontal  and  vertical  radii  of  the  ellipse.  Start  and  Stop  are  the  starting  and  stopping
                 angles of the part of the ellipse.  They are measured counterclockwise from the X-axis.

       Errors:    None.

     See also:    Arc (116) Circle (117), FillEllipse (118)
                 8.4.11        FillEllipse

Declaration:      Procedure  FillEllipse  (X,Y  :  Integer;  Xradius,YRadius:    Word);

Description:      Ellipse draws an ellipse with center at (X,Y). XRadius and Yradius are the horizontal
                 and vertical radii of the ellipse.  The ellipse is filled with the current color and fill-style.

       Errors:    None.

     See also:    Arc (116) Circle (117), GetArcCoords (119),PieSlice (126), Sector (128)
                 8.4.12        FillPoly

Declaration:      Procedure  FillPoly  (NumberOfPoints  :    Word;  Var  PolyPoints);

Description:      Draws a polygone with NumberOfPoints corner points and fills it using the current color
                 and line-style.  PolyPoints is an array of type PointType.

       Errors:    None.

     See also:    Bar (116), seepBar3D, Rectangle (127)
                 8.4.13        FloodFill

Declaration:      Procedure  FloodFill  (X,Y  :  Integer;  BorderColor  :    Word);

Description:      Fills the area containing the point (X,Y), bounded by the color BorderColor.

       Errors:    None

     See also:    SetColor (129), SetBkColor (128)

                                                                                 118

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.14        GetArcCoords

Declaration:      Procedure  GetArcCoords  (Var  ArcCoords  :    ArcCoordsType);

Description:      GetArcCoords returns the coordinates of the latest Arc or Ellipse call.

       Errors:    None.

     See also:    Arc (116), Ellipse (118)
                 8.4.15        GetAspectRatio

Declaration:      Procedure  GetAspectRatio  (Var  Xasp,Yasp  :    Word);

Description:      GetAspectRatio determines the effective resolution of the screen.  The aspect ration can
                 the be calculated as Xasp/Yasp.

       Errors:    None.

     See also:    InitGraph (124),SetAspectRatio (128)
                 8.4.16        GetBkColor

Declaration:      Function  GetBkColor  :    Word;

Description:      GetBkColor returns the current background color (the palette entry).

       Errors:    None.

     See also:    GetColor (119),SetBkColor (128)
                 8.4.17        GetColor

Declaration:      Function  GetColor  :    Word;

Description:      GetColor returns the current drawing color (the palette entry).

       Errors:    None.

     See also:    GetColor (119),SetBkColor (128)
                 8.4.18        GetDefaultPalette

Declaration:      Procedure  GetDefaultPalette  (Var  Palette  :    PaletteType);

Description:      Returns the current palette in Palette.

       Errors:    None.

     See also:    GetColor (119), GetBkColor (119)
                 8.4.19        GetDriverName

Declaration:      Function  GetDriverName  :    String;

Description:      GetDriverName returns a string containing the name of the current driver.

       Errors:    None.

     See also:    GetModeName (121), InitGraph (124)



                                                                                 119

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.20        GetFillPattern

Declaration:      Procedure  GetFillPattern  (Var  FillPattern  :    FillPatternType);

Description:      GetFillPattern returns an array with the current fill-pattern in FillPattern

       Errors:    None

     See also:    SetFillPattern (129)
                 8.4.21        GetFillSettings

Declaration:      Procedure  GetFillSettings  (Var  FillInfo  :    FillSettingsType);

Description:      GetFillSettings returns the current fill-settings in FillInfo

       Errors:    None.

     See also:    SetFillPattern (129)
                 8.4.22        GetGraphMode

Declaration:      Function  GetGraphMode  :    Integer;

Description:      GetGraphMode returns the current graphical modus

       Errors:    None.

     See also:    InitGraph (124)
                 8.4.23        GetImage

Declaration:      Procedure  GetImage  (X1,Y1,X2,Y2  :    Integer,  Var  Bitmap;

Description:      GetImage Places a copy of the screen area (X1,Y1) to X2,Y2 in BitMap

       Errors:    Bitmap must have enough room to contain the image.

     See also:    ImageSize (123), PutImage (126)
                 8.4.24        GetLineSettings

Declaration:      Procedure  GetLineSettings  (Var  LineInfo  :    LineSettingsType);

Description:      GetLineSettings returns the current Line settings in LineInfo

       Errors:    None.

     See also:    SetLineStyle (130)
                 8.4.25        GetMaxColor

Declaration:      Function  GetMaxColor  :    Word;

Description:      GetMaxColor returns the maximum color-number which can be set with SetColor.  Con-
                 trary to Turbo Pascal, this color isn't always guaranteed to be white (for instance in 256+
                 color modes).

       Errors:    None.

     See also:    SetColor (129), GetPaletteSize (122)



                                                                                 120

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.26        GetMaxMode

Declaration:      Function  GetMaxMode  :    Word;

Description:      GetMaxMode returns the highest modus for the current driver.

       Errors:    None.

     See also:    InitGraph (124)
                 8.4.27        GetMaxX

Declaration:      Function  GetMaxX  :  Word;

Description:      GetMaxX returns the maximum horizontal screen length

       Errors:    None.

     See also:    GetMaxY (121)
                 8.4.28        GetMaxY

Declaration:      Function  GetMaxY  :  Word;

Description:      GetMaxY returns the maximum number of screen lines

       Errors:    None.

     See also:    GetMaxY (121)
                 8.4.29        GetModeName

Declaration:      Function  GetModeName  (Var  modus  :    Integer)  :    String;

Description:      Returns a string with the name of modus Modus

       Errors:    None.

     See also:    GetDriverName (119), InitGraph (124)
                 8.4.30        GetModeRange

Declaration:      Procedure  GetModeRange  (Driver  :    Integer;
                 LoModus,  HiModus:    Integer);

Description:      GetModeRange returns the Lowest and Highest modus of the currently installed driver.  If
                 no modes are supported for this driver, HiModus will be -1.

       Errors:    None.

     See also:    InitGraph (124)
                 8.4.31        GetPalette

Declaration:      Procedure  GetPalette  (Var  Palette  :    PaletteType);

Description:      GetPalette returns in Palette the current palette.

       Errors:    None.

     See also:    GetPaletteSize (122), SetPalette (130)



                                                                                 121

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.32        GetPaletteSize

Declaration:      Function  GetPaletteSize  :    Word;

Description:      GetPaletteSize returns the maximum number of entries in the current palette.

       Errors:    None.

     See also:    GetPalette (121), SetPalette (130)
                 8.4.33        GetPixel

Declaration:      Function  GetPixel  (X,Y  :  Integer)  :    Word;

Description:      GetPixel returns the color of the point at (X,Y)

       Errors:    None.

     See also:
                 8.4.34        GetTextSettings

Declaration:      Procedure  GetTextSettings  (Var  TextInfo  :    TextSettingsType);

Description:      GetTextSettings  returns  the  current  text  style  settings  :  The  font,  direction,  size  and
                 placement as set with SetTextStyle and SetTextJustify

       Errors:    None.

     See also:    SetTextStyle (131), SetTextJustify (131)
                 8.4.35        GetViewSettings

Declaration:      Procedure  GetViewSettings  (Var  ViewPort  :    ViewPortType);

Description:      GetViewSettings returns the current viewport and clipping settings in ViewPort.

       Errors:    None.

     See also:    SetViewPort (132)
                 8.4.36        GetX

Declaration:      Function  GetX  :  Integer;

Description:      GetX returns the X-coordinate of the current position of the graphical pointer

       Errors:    None.

     See also:    GetY (122)
                 8.4.37        GetY

Declaration:      Function  GetY  :  Integer;

Description:      GetY returns the Y-coordinate of the current position of the graphical pointer

       Errors:    None.

     See also:    GetX (122)



                                                                                 122

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.38        GraphDefaults

Declaration:      Procedure  GraphDefaults  ;

Description:      GraphDefaults resets all settings for viewport, palette, foreground and background pattern,
                 line-style and pattern,  filling style,  filling color and pattern,  font,  text-placement and text
                 size.

       Errors:    None.

     See also:    SetViewPort (132), SetFillStyle (129), SetColor (129), SetBkColor (128), SetLineStyle (130)
                 8.4.39        GraphErrorMsg

Declaration:      Function  GraphErrorMsg  (ErrorCode  :    Integer)  :    String;

Description:      GraphErrorMsg returns a string describing the error Errorcode.  This string can be used
                 to let the user know what went wrong.

       Errors:    None.

     See also:    GraphResult (123)
                 8.4.40        GraphResult

Declaration:      Function  GraphResult  :    Integer;

Description:      GraphResult returns an error-code for the last graphical operation.  If the returned value
                 is zero, all went well.  A value different from zero means an error has occurred.  besides all
                 operations which draw something on the screen, the following procedures also can produce
                 a GraphResult different from zero:


                      oInstallUserFont (124)

                      oSetLineStyle (130)

                      oSetWriteMode (132)

                      oSetFillStyle (129)

                      oSetTextJustify (131)

                      oSetGraphMode (130)

                      oSetTextStyle (131)


       Errors:    None.

     See also:    GraphErrorMsg (123)
                 8.4.41        ImageSize

Declaration:      Function  ImageSize  (X1,Y1,X2,Y2  :    Integer)  :    Word;

Description:      ImageSize returns the number of bytes needed to store the image in the rectangle defined
                 by (X1,Y1) and (X2,Y2).

       Errors:    None.

     See also:    GetImage (120)

                                                                                 123

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.42        InitGraph

Declaration:      Procedure  InitGraph  (var  GraphDriver,GraphModus  :    integer;
                 const  PathToDriver  :    string);

Description:      InitGraph initializes the graph package.  GraphDriver has two valid values: GraphDriver=0
                 which performs an auto detect and initializes the highest possible mode with the most colors.
                 1024x768x64K is the highest possible resolution supported by the driver, if you need a higher
                 resolution, you must edit MODES.PPI. If you need another mode, then set GraphDriver to
                 a  value  different  from  zero  and  graphmode  to  the  mode  you  wish  (VESA  modes  where
                 640x480x256  is  101h  etc.).   PathToDriver  is  only  needed,  if  you  use  the  BGI  fonts  from
                 Borland.

       Errors:    None.

     See also:    Introduction, (page 108), DetectGraph (117), CloseGraph (117), GraphResult (123)


                 Example:


                 var
                     gd,gm  :  integer;
                     PathToDriver  :  string;
                 begin
                     gd:=detect;  {  highest  possible  resolution  }
                     gm:=0;  {  not  needed,  auto  detection  }
                     PathToDriver:='C:\PP\BGI';  {  path  to  BGI  fonts,
                                                                     drivers  aren't  needed  }
                     InitGraph(gd,gm,PathToDriver);
                     if  GraphResult<>grok  then
                         halt;  .....  {  whatever  you  need  }
                     CloseGraph;  {  restores  the  old  graphics  mode  }
                 end.
                 8.4.43        InstallUserDriver

Declaration:      Function  InstallUserDriver  (DriverPath  :    String;
                 AutoDetectPtr:    Pointer)  :    Integer;

Description:      InstallUserDriver adds the device-driver DriverPath to the list of .BGI drivers.  AutoDetectPtr
                 is a pointer to a possible auto-detect function.

       Errors:    None.

     See also:    InitGraph (124), InstallUserFont (124)
                 8.4.44        InstallUserFont

Declaration:      Function  InstallUserFont  (FontPath  :    String)  :    Integer;

Description:      InstallUserFont adds the font in FontPath to the list of fonts of the .BGI system.

       Errors:    None.

     See also:    InitGraph (124), InstallUserDriver (124)



                                                                                 124

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.45        Line

Declaration:      Procedure  Line  (X1,Y1,X2,Y2  :    Integer);

Description:      Line draws a line starting from (X1,Y1 to (X2,Y2), in the current line style and color.  The
                 current position is put to (X2,Y2)

       Errors:    None.

     See also:    LineRel (125),LineTo (125)
                 8.4.46        LineRel

Declaration:      Procedure  LineRel  (DX,DY  :  Integer);

Description:      LineRel draws a line starting from the current pointer position to the point(DX,DY, relative
                 to the current position,  in the current line style and color.  The Current Position is set to
                 the endpoint of the line.

       Errors:    None.

     See also:    Line (125), LineTo (125)
                 8.4.47        LineTo

Declaration:      Procedure  LineTo  (DX,DY  :  Integer);

Description:      LineTo draws a line starting from the current pointer position to the point(DX,DY, relative
                 to the current position,  in the current line style and color.  The Current position is set to
                 the end of the line.

       Errors:    None.

     See also:    LineRel (125),Line (125)
                 8.4.48        MoveRel

Declaration:      Procedure  MoveRel  (DX,DY  :  Integer;

Description:      MoveRel moves the pointer to the point (DX,DY), relative to the current pointer position

       Errors:    None.

     See also:    MoveTo (125)
                 8.4.49        MoveTo

Declaration:      Procedure  MoveTo  (X,Y  :  Integer;

Description:      MoveTo moves the pointer to the point (X,Y).

       Errors:    None.

     See also:    MoveRel (125)

                                                                                 125

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.50        OutText

Declaration:      Procedure  OutText  (Const  TextString  :    String);

Description:      OutText puts TextString on the screen, at the current pointer position, using the current
                 font and text settings.  The current position is moved to the end of the text.

       Errors:    None.

     See also:    OutTextXY (126)
                 8.4.51        OutTextXY

Declaration:      Procedure  OutTextXY  (X,Y  :  Integer;  Const  TextString  :    String);

Description:      OutText puts TextString on the screen, at position (X,Y), using the current font and text
                 settings.  The current position is moved to the end of the text.

       Errors:    None.

     See also:    OutText (126)
                 8.4.52        PieSlice

Declaration:      Procedure  PieSlice  (X,Y  :  Integer;
                 Start,Stop,Radius  :    Word);

Description:      PieSlice draws and fills a sector of a circle with center (X,Y) and radius Radius, starting
                 at angle Start and ending at angle Stop.

       Errors:    None.

     See also:    Arc (116), Circle (117), Sector (128)
                 8.4.53        PutImage

Declaration:      Procedure  PutImage  (X1,Y1  :    Integer;  Var  Bitmap;  How  :    word)  ;

Description:      PutImage Places the bitmap in Bitmap on the screen at (X1,Y1).  How determines how the
                 bitmap will be placed on the screen.  Possible values are :


                      oCopyPut

                      oXORPut

                      oORPut

                      oAndPut

                      oNotPut


       Errors:    None

     See also:    ImageSize (123),GetImage (120)

                                                                                 126

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.54        PutPixel

Declaration:      Procedure  PutPixel  (X,Y  :  Integer;  Color  :    Word);

Description:      Puts a point at (X,Y) using color Color

       Errors:    None.

     See also:    GetPixel (122)
                 8.4.55        Rectangle

Declaration:      Procedure  Rectangle  (X1,Y1,X2,Y2  :    Integer);

Description:      Draws a rectangle with corners at (X1,Y1) and (X2,Y2), using the current color and style.

       Errors:    None.

     See also:    Bar (116), Bar3D (116)
                 8.4.56        RegisterBGIDriver

Declaration:      Function  RegisterBGIDriver  (Driver  :    Pointer)  :    Integer;

Description:      Registers a user-defined BGI driver

       Errors:    None.

     See also:    InstallUserDriver (124), RegisterBGIFont (127)
                 8.4.57        RegisterBGIFont

Declaration:      Function  RegisterBGIFont  (Font  :    Pointer)  :    Integer;

Description:      Registers a user-defined BGI driver

       Errors:    None.

     See also:    InstallUserFont (124), RegisterBGIDriver (127)
                 8.4.58        RestoreCRTMode

Declaration:      Procedure  RestoreCRTMode  ;

Description:      Restores the screen modus which was active before the graphical modus was started.

                 To get back to the graph mode you were last in, you can use SetGraphMode(GetGraphMode)

       Errors:    None.

     See also:    InitGraph (124)
                                                                                 127

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.59        Sector

Declaration:      Procedure  Sector  (X,Y  :  Integer;
                 Start,Stop,XRadius,YRadius  :    Word);

Description:      Sector  draws  and  fills  a  sector  of  an  ellipse  with  center  (X,Y)  and  radii  XRadius  and
                 YRadius, starting at angle Start and ending at angle Stop.

       Errors:    None.

     See also:    Arc (116), Circle (117), PieSlice (126)
                 8.4.60        SetActivePage

Declaration:      Procedure  SetActivePage  (Page  :    Word);

Description:      Sets Page as the active page for all graphical output.

       Errors:    None.

     See also:
                 8.4.61        SetAllPallette

Declaration:      Procedure  SetAllPallette  (Var  Palette);

Description:      Sets the current palette to Palette.  Palette is an untyped variable, usually pointing to a
                 record of type PaletteType

       Errors:    None.

     See also:    GetPalette (121)
                 8.4.62        SetAspectRatio

Declaration:      Procedure  SetAspectRatio  (Xasp,Yasp  :    Word);

Description:      Sets the aspect ratio of the current screen to Xasp/Yasp.

       Errors:    None

     See also:    InitGraph (124), GetAspectRatio (119)
                 8.4.63        SetBkColor

Declaration:      Procedure  SetBkColor  (Color  :    Word);

Description:      Sets the background color to Color.

       Errors:    None.

     See also:    GetBkColor (119), SetColor (129)

                                                                                 128

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.64        SetColor

Declaration:      Procedure  SetColor  (Color  :    Word);

Description:      Sets the foreground color to Color.

       Errors:    None.

     See also:    GetColor (119), SetBkColor (128)
                 8.4.65        SetFillPattern

Declaration:      Procedure  SetFillPattern  (FillPattern  :    FillPatternType,
                 Color  :    Word);

Description:      SetFillPattern sets the current fill-pattern to FillPattern, and the filling color to Color
                 The pattern is an 8x8 raster, corresponding to the 64 bits in FillPattern.

       Errors:    None

     See also:    GetFillPattern (120), SetFillStyle (129)
                 8.4.66        SetFillStyle

Declaration:      Procedure  SetFillStyle  (Pattern,Color  :    word);

Description:      SetFillStyle  sets  the  filling  pattern  and  color  to  one  of  the  predefined  filling  patterns.
                 Pattern can be one of the following predefined constants :

                      oEmptyFill   Uses backgroundcolor.

                      oSolidFill   Uses filling color

                      oLineFill   Fills with horizontal lines.

                      oltSlashFill Fills with lines from left-under to top-right.

                      oSlashFill   Idem as previous, thick lines.

                      oBkSlashFill Fills with thick lines from left-Top to bottom-right.

                      oLtBkSlashFill Idem as previous, normal lines.

                      oHatchFill Fills with a hatch-like pattern.

                      oXHatchFill Fills with a hatch pattern, rotated 45 degrees.

                      oInterLeaveFill

                      oWideDotFill Fills with dots, wide spacing.

                      oCloseDotFill Fills with dots, narrow spacing.

                      oUserFill Fills with a user-defined pattern.

       Errors:    None.

     See also:    SetFillPattern (129)
                 8.4.67        SetGraphBufSize

Declaration:      Procedure  SetGraphBufSize  (BufSize  :    Word);

Description:      SetGraphBufSize is a dummy function which does not do anything; it is no longer needed.

       Errors:    None.

     See also:



                                                                                 129

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.68        SetGraphMode

Declaration:      Procedure  SetGraphMode  (Mode  :    Integer);

Description:      SetGraphMode sets the graphical mode and clears the screen.

       Errors:    None.

     See also:    InitGraph (124)
                 8.4.69        SetLineStyle

Declaration:      Procedure  SetLineStyle  (LineStyle,Pattern,Width  :    Word);

Description:      SetLineStyle sets the drawing style for lines.  You can specify a LineStyle which is one
                 of the following pre-defined constants:


                      oSolidln=0; draws a solid line.

                      oDottedln=1; Draws a dotted line.

                      oCenterln=2; draws a non-broken centered line.

                      oDashedln=3; draws a dashed line.

                      oUserBitln=4; Draws a User-defined bit pattern.


                 If UserBitln is specified then Pattern contains the bit pattern.  In all another cases, Pattern
                 is ignored.  The parameter Width indicates how thick the line should be.  You can specify
                 one of the following pre-defined constants:


                      oNormWidth=1

                      oThickWidth=3


       Errors:    None.

     See also:    GetLineSettings (120)
                 8.4.70        SetPalette

Declaration:      Procedure  SetPalette  (ColorNr  :    Word;  NewColor  :    ShortInt);

Description:      SetPalette changes the ColorNr-th entry in the palette to NewColor

       Errors:    None.

     See also:    SetAllPallette (128),SetRGBPalette (130)
                 8.4.71        SetRGBPalette

Declaration:      Procedure  SetRGBPalette  (ColorNr,Red,Green,Blue  :    Integer);

Description:      SetRGBPalette sets the ColorNr-th entry in the palette to the color with RGB-values Red,
                 Green  Blue.

       Errors:    None.

     See also:    SetAllPallette (128), SetPalette (130)


                                                                                 130

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.72        SetTextJustify

Declaration:      Procedure  SetTextJustify  (Horizontal,Vertical  :    Word);

Description:      SetTextJustify  controls  the  placement  of  new  text,  relative  to  the  (graphical)  cursor
                 position.  Horizontal  controls  horizontal  placement,  and  can  be  one  of  the  following  pre-
                 defined constants:


                      oLeftText=0; Text is set left of the pointer.

                      oCenterText=1; Text is set centered horizontally on the pointer.

                      oRightText=2; Text is set to the right of the pointer.


                 Vertical controls the vertical placement of the text, relative to the (graphical) cursor posi-
                 tion.  Its value can be one of the following pre-defined constants :


                      oBottomText=0; Text is placed under the pointer.

                      oCenterText=1; Text is placed centered vertically on the pointer.

                      oTopText=2;Text is placed above the pointer.


       Errors:    None.

     See also:    OutText (126), OutTextXY (126)
                 8.4.73        SetTextStyle

Declaration:      Procedure  SetTextStyle  (Font,Direction,Magnitude  :    Word);

Description:      SetTextStyle controls the style of text to be put on the screen.  pre-defined constants for
                 Font are:


                      oDefaultFont=0;

                      oTriplexFont=2;

                      oSmallFont=2;

                      oSansSerifFont=3;

                      oGothicFont=4;


                 Pre-defined constants for Direction are :


                      oHorizDir=0;

                      oVertDir=1;


       Errors:    None.

     See also:    GetTextSettings (122)
                 8.4.74        SetUserCharSize

Declaration:      Procedure  SetUserCharSize  (Xasp1,Xasp2,Yasp1,Yasp2  :    Word);

Description:      Sets  the  width  and  height  of  vector-fonts.  The  horizontal  size  is  given  by  Xasp1/Xasp2,
                 and the vertical size by Yasp1/Yasp2.

       Errors:    None.

     See also:    SetTextStyle (131)



                                                                                 131

                 ___________________________________________________________________________8.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 8.4.75        SetViewPort

Declaration:      Procedure  SetViewPort  (X1,Y1,X2,Y2  :    Integer;  Clip  :    Boolean);

Description:      Sets the current graphical viewport (window) to the rectangle defined by the top-left corner
                 (X1,Y1) and the bottom-right corner (X2,Y2).  If  Clip is true, anything drawn outside the
                 viewport (window) will be clipped (i.e.  not drawn).  Coordinates specified after this call are
                 relative to the top-left corner of the viewport.

       Errors:    None.

     See also:    GetViewSettings (122)
                 8.4.76        SetVisualPage

Declaration:      Procedure  SetVisualPage  (Page  :    Word);

Description:      SetVisualPage sets the video page to page number Page.

       Errors:    None

     See also:    SetActivePage (128)
                 8.4.77        SetWriteMode

Declaration:      Procedure  SetWriteMode  (Mode  :    Integer);

Description:      SetWriteMode controls the drawing of lines on the screen.  It controls the binary operation
                 used when drawing lines on the screen.  Mode can be one of the following pre-defined constants:


                      oCopyPut=0;

                      oXORPut=1;


       Errors:    None.

     See also:
                 8.4.78        TextHeight

Declaration:      Function  TextHeight  (S  :  String)  :    Word;

Description:      TextHeight returns the height (in pixels) of the string S in the current font and text-size.

       Errors:    None.

     See also:    TextWidth (132)
                 8.4.79        TextWidth

Declaration:      Function  TextWidth  (S  :  String)  :    Word;

Description:      TextHeight returns the width (in pixels) of the string S in the current font and text-size.

       Errors:    None.

     See also:    TextHeight (132)

                                                                                 132

____________________________________________________________________________________8.5.___TARGET_SPECIFIC_ISSUES__________________*
 *___
8.5        Target  specific  issues


In what follows we describe some things that are different on the various platforms:
8.5.1       dos

8.5.2       Windows  32-bit

8.5.3       linux

                                                                133


 Chapter   9


 The   HEAPTRC   unit.



 This chapter describes the HEAPTRC unit for Free Pascal.  It was written by Pierre Muller.
 It is system independent, and works on all supported systems.
 9.1        Purpose


 The HEAPTRC unit can be used to debug your memory allocation/deallocation.  It keeps
 track of the calls to getmem/freemem, and, implicitly, of New/Dispose statements.

 When  the  program  exits,  or  when  you  request  it  explicitly.  It  displays  the  total  memory
 used,  and  then  dumps  a  list  of  blocks  that  were  allocated  but  not  freed.  It  also  displays
 where the memory was allocated.

 If there are any inconsistencies, such as memory blocks being allocated or freed twice, or a
 memory block that is released but with wrong size, this will be displayed also.

 The information that is stored/displayed can be customized using some constants.
 9.2        Usage


 All that you need to do is to include heaptrc in the uses clause of your program.  Make sure
 that  it  is  the  first  unit  in  the  clause,  otherwise  memory  allocated  in  initialization  code  of
 units that precede the heaptrc unit will not be accounted for, causing an incorrect memory
 usage report.

 If you use the -gh switch,  the compiler will insert the unit by itself,  so you don't have to
 include it in your uses clause.

 The following example shows how to use the heaptrc unit.

________________________________________________________________________________________________________________________________
 Program       h e a p e x;


 {  Program       u s e d  to   d e m o n s t r a t et h e  u s a g e  o f  h e a p t r c u n i t }


 Uses     h e a p t r c;


 Var    P1   :  ^ L o n g i n t;
        P2   :   P o i n t e r;
        I  :   l o n g i n t;

                                                             134

 __________________________________________________________________9.3.___CONSTANTS,_TYPES_AND_VARIABLES___________________________*
 *____
 b e g i n
    New  ( P1  ) ;
    / /   c a u s e s p r e v i o u s a l l o c a t i o nnot   to    be   de - a l l o c a t e d
    New  ( P1  ) ;
    D i s p o s e(P1  ) ;
    For    I :=1    to   1 0  do
        b e g i n
       GetMem       (P2  , 1 2 8 ) ;
        / /  When     I  i s  e v e n ,  d e a l l o c a t eb l o c k.  We    l o o s e 5  t i m e s 1 2 8
        / /  b y t e s  t h i s way  .
        I f  ( I  mod    2 )  =  0   Then     FreeMem     ( P2  , 1 2 8 ) ;
        end  ;
    GetMem     (P2  , 1 2 8 ) ;
    / /   T h i s w i l l  p r o v o k e an   e r r o r and    a   memory      dump
    Freemem       ( P2  , 6 4 ) ;
_end__._________________________________________________________________________________________________________________________

 This is the memory dump shown when running this program:


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


 If you use the lineinfo unit (or use the -gl switch) as well, then heaptrc will also give you the
 filenames and line-numbers of the procedures in the backtrace:


 Marked  memory  at  00410DA0  invalid
 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.
 9.3        Constants,  Types  and  variables


 The FillExtraInfoType is a procedural type used in the SetExtraInfo (137) call.

________________________________________________________________________________________________________________________________
 type
________F_i_l_l_E_x_t_r_a_I_n_f_o_T_y_p=e__p_r_o_c_e_d_u_r(ep__:___p_o_i_n_t_e_r)_;_____________________________________________


 The following typed constants allow to fine-tune the standard dump of the memory usage
 by DumpHeap (136):

________________________________________________________________________________________________________________________________
 c o n s t
                                                                 135

                 ___________________________________________________________________________9.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    t r a c e s i z e=  8 ;
                    q u i c k t r a c e:   b o o l e a n=   t r u e;
                    H a l t O n E r r o r:   b o o l e a n=   t r u e;
                    k e e p r e l e a s e d:  b o o l e a n =   f a l s e;
                    a d d __t a i l :   b o o l e a n=   t r u e;
                ____u_s_e_c_r_c_:___b_o_o_l_e_a_n=___t_r_u_e_______________________________________________________________________*
 *_____________

                 Tracesize specifies how many levels of calls are displayed of the call stack during the memory
                 dump.   If  you  specify  keepreleased:=True  then  half  the  TraceSize  is  reserved  for  the
                 GetMem call stack,  and the other half is reserved for the FreeMem call stack.  For example,
                 the  default  value  of  8  will  cause  eight  levels  of  call  frames  to  be  dumped  for  the  getmem
                 call if  keepreleased is False.  If  KeepReleased is true, then 4 levels of call frames will be
                 dumped for the GetMem call and 4 frames wil be dumped for the FreeMem call.  If you want
                 to change this value, you must recode the heaptrc unit.

                 Quicktrace determines whether the memory manager checks whether a block that is about
                 to  be  released  is  allocated  correctly.   This  is  a  rather  time  consuming  search,  and  slows
                 program execution significantly, so by default it is set to False.

                 If HaltOnError is set to True then an illegal call to FreeMem will cause the memory manager
                 to execute a halt(1) instruction, causing a memory dump.  By Default it is set to True.

                 If  keepreleased  is  set  to  true,  then  a  list  of  freed  memory  blocks  is  kept.  This  is  useful
                 if you suspect that the same memory block is released twice.  However, this option is very
                 memory intensive, so use it sparingly, and only when it's really necessary.

                 If  add__ tail is True (the default) then a check is also performed on the memory location
                 just behind the allocated memory.

                 If  usecrc is True (the default) then a crc check is performed on locations before and after
                 the allocated memory.  This is useful to detect memory overwrites.
                 9.4        Functions  and  procedures



                 9.4.1       DumpHeap

Declaration:      procedure  DumpHeap;

Description:      DumpHeap dumps to standard output a summary of memory usage.  It is called automatically
                 by the heaptrc unit when your program exits (by instaling an exit procedure), but it can be
                 called at any time

       Errors:    None.

     See also:    MarkHeap (136)
                 9.4.2       MarkHeap

Declaration:      procedure  MarkHeap;

Description:      MarkHeap marks all memory blocks with a special signature.  You can use this if you think
                 that you corruped the memory.

       Errors:    None.

     See also:    DumpHeap (136)
                                                                                 136

                 ___________________________________________________________________________9.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 9.4.3       SetExtraInfo

Declaration:      procedure  SetExtraInfo(  size  :    longint;func  :    FillExtraInfoType);

Description:      You can use SetExtraInfo to store extra info in the blocks that the heaptrc unit reserves
                 when  tracing  getmem  calls.   Size  indicates  the  size  (in  bytes)  that  the  trace  mechanism
                 should reserve for your extra information.  For each call to getmem, func will be called, and
                 passed a pointer to the memory reserved.

                 When dumping the memory summary, the extra info is shown as Longint values.

       Errors:    You can only call SetExtraInfo if no memroy has been allocated yet.  If memory was already
                 allocated prior to the call to SetExtraInfo, then an error will be displayed on standard error
                 output, and a DumpHeap (136) is executed.

     See also:    DumpHeap (136),SetHeapTraceOutput (138)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       h e a p e x;


                 {  Program       u s e d  to   d e m o n s t r a t et h e  u s a g e  o f  h e a p t r c u n i t }


                 Uses     h e a p t r c;


                 Var    P1   :  ^ L o n g i n t;
                        P2   :   P o i n t e r;
                        I  :   l o n g i n t;
                        Marker      :   L o n g i n t;


                 Procedure        S e t M a r k e r( P   :   p o i n t e r) ;


                 Type     P L o n g i n t=  ^ L o n g i n t;


                 b e g i n
                    P L o n g i n t(P )^:=   Marker    ;
                 end  ;


                 Procedure          P a r t 1;


                 b e g i n
                    / /   B l o c k s a l l o c a t e dh e r e  a r e  marked      with    $FFAAFFAA         =  -5570646
                    Marker      : =  $FFAAFFAA       ;
                    New  ( P1  ) ;
                    New  ( P1  ) ;
                    D i s p o s e(P1  ) ;
                    For    I :=1    to   1 0  do
                        b e g i n
                       GetMem       (P2  , 1 2 8 ) ;
                        I f  ( I  mod    2 )  =  0   Then     FreeMem     ( P2  , 1 2 8 ) ;
                        end  ;
                    GetMem     (P2  , 1 2 8 ) ;
                 end  ;


                 Procedure          P a r t 2;


                 b e g i n
                    / /   B l o c k s a l l o c a t e dh e r e  a r e  marked      with    $FAFAFAFA         =  -84215046
                    Marker      : =  $FAFAFAFA       ;
                    New  ( P1  ) ;
                    New  ( P1  ) ;



                                                                                 137

                 ___________________________________________________________________________9.4.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    D i s p o s e(P1  ) ;
                    For    I :=1    to   1 0  do
                        b e g i n
                       GetMem       (P2  , 1 2 8 ) ;
                        I f  ( I  mod    2 )  =  0   Then     FreeMem     ( P2  , 1 2 8 ) ;
                        end  ;
                    GetMem     (P2  , 1 2 8 ) ;
                 end  ;


                 b e g i n
                   S e t E x t r a I n f(oS i z e O f(Marker    ) ,@SetMarker        ) ;
                   W r i t e l n( ' P a r t|_|1 ') ;
                   p a r t 1;
                   W r i t e l n('P a r t|_|2 ') ;
                   p a r t 2;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 9.4.4       SetHeapTraceOutput

Declaration:      Procedure  SetHeapTraceOutput(const  name  :    string);

Description:      SetHeapTraceOutput  sets  the  filename  into  which  heap  trace  info  will  be  written.   By
                 default information is written to standard output,  this function allows you to redirect the
                 information to a file with full filename name.

       Errors:    If the file cannot be written to, errors will occur when writing the trace.

     See also:    SetExtraInfo (137)



                                                                                 138


Chapter   10


The   IPC   unit.



This chapter describes the IPC unit for Free Pascal.  It was written for linux by Micha"el Van
Canneyt.  It  gives  all  the  functionality  of  system  V  Inter-Process  Communication:  shared
memory, semaphores and messages.  It works only on the linux operating system.

The chapter is divided in 2 sections:


    o  The first section lists types, constants and variables from the interface part of the unit.

    o  The second section describes the functions defined in the unit.
10.1          Types,  Constants  and  variables  :



10.1.1        Variables

Var
   IPCerror  :  longint;


The IPCerror variable is used to report errors, by all calls.
10.1.2        Constants

Many constants here are provided for completeness only, and should under normal circum-
stances not be used by the programmer.


Const
   IPC_CREAT    =    1  shl  9;    {  create  if  key  is  nonexistent  }
   IPC_EXCL     =    2  shl  9;    {  fail  if  key  exists  }
   IPC_NOWAIT  =    4  shl  9;    {  return  error  on  wait  }


These constants are used in the various xxxget calls.


   IPC_RMID  =  0;        {  remove  resource  }
   IPC_SET    =  1;        {  set  ipc_perm  options  }
   IPC_STAT  =  2;        {  get  ipc_perm  options  }
   IPC_INFO  =  3;        {  see  ipcs  }


These constants can be passed to the various xxxctl calls.
                                                            139

_____________________________________________________________10.1.___TYPES,_CONSTANTS_AND_VARIABLES_:______________________________*
 *___
const
   MSG_NOERROR  =  1  shl  12;
   MSG_EXCEPT    =  2  shl  12;
   MSGMNI  =  128;
   MSGMAX  =  4056;
   MSGMNB  =  16384;


These constants are used in the messaging system, they are not for use by the programmer.


const
   SEM_UNDO  =  $1000;
   GETPID  =  11;
   GETVAL  =  12;
   GETALL  =  13;
   GETNCNT  =  14;
   GETZCNT  =  15;
   SETVAL  =  16;
   SETALL  =  17;


These constants call be specified in the semop (148) call.


   SEMMNI  =  128;
   SEMMSL  =  32;
   SEMMNS  =  (SEMMNI  *  SEMMSL);
   SEMOPM  =  32;
   SEMVMX  =  32767;


These constanst are used internally by the semaphore system, they should not be used by
the programmer.


const
   SHM_R          =  4  shl  6;
   SHM_W          =  2  shl  6;
   SHM_RDONLY  =  1  shl  12;
   SHM_RND       =  2  shl  12;
   SHM_REMAP    =  4  shl  12;
   SHM_LOCK     =  11;
   SHM_UNLOCK  =  12;


These constants are used in the shmctl (154) call.
10.1.3        Types

The  following  two  types  are  provided  because  they  are  needed.  One  they  they  should  be
defined in the system unit, however.


Type
   PULong  =  ^Cardinal;
   PWord    =  ^Word;


Type
    TKey     =  Longint;


TKey is the type returned by the ftok (144) key generating function.



                                                                140

_____________________________________________________________10.1.___TYPES,_CONSTANTS_AND_VARIABLES_:______________________________*
 *___
type
   PIPC_Perm  =  ^TIPC_Perm;
   TIPC_Perm  =  record
      key  :  TKey;
      uid,
      gid,
      cuid,
      cgid,
      mode,
      seq  :  Word;
   end;


The TIPC__ Perm structure is used in all IPC systems to specify the permissions.


Type
   PSHMid_DS  =  ^TSHMid_ds;
   TSHMid_ds  =  record
      shm_perm    :  TIPC_Perm;
      shm_segsz  :  longint;
      shm_atime  :  longint;
      shm_dtime  :  longint;
      shm_ctime  :  longint;
      shm_cpid    :  word;
      shm_lpid    :  word;
      shm_nattch  :  integer;
      shm_npages  :  word;
      shm_pages    :  Pointer;
      attaches     :  pointer;
   end;


The TSHMid__ ds strucure is used in the shmctl (154) call to set or retrieve settings concerning
shared memory.


type
   PSHMinfo  =  ^TSHMinfo;
   TSHMinfo  =  record
      shmmax  :  longint;
      shmmin  :  longint;
      shmmni  :  longint;
      shmseg  :  longint;
      shmall  :  longint;
   end;


The TSHMinfo record is used by the shared memory system, and should not be accessed by
the programer directly.


type
   PMSG  =  ^TMSG;
   TMSG  =  record
      msg_next    :  PMSG;
      msg_type    :  Longint;
      msg_spot    :  PChar;
      msg_stime  :  Longint;
      msg_ts       :  Integer;
   end;



                                                                141

_____________________________________________________________10.1.___TYPES,_CONSTANTS_AND_VARIABLES_:______________________________*
 *___
The TMSG record is used in the handling of message queues.  There should be few cases where
the programmer needs to access this data.


type
   PMSQid_ds  =  ^TMSQid_ds;
   TMSQid_ds  =  record
      msg_perm     :  TIPC_perm;
      msg_first    :  PMsg;
      msg_last     :  PMsg;
      msg_stime    :  Longint;
      msg_rtime    :  Longint;
      msg_ctime    :  Longint;
      wwait          :  Pointer;
      rwait          :  pointer;
      msg_cbytes  :  word;
      msg_qnum     :  word;
      msg_qbytes  :  word;
      msg_lspid    :  word;
      msg_lrpid    :  word;
   end;


The TMSQid__ ds record is returned by the msgctl (145) call, and contains all data about a
message queue.


   PMSGbuf  =  ^TMSGbuf;
   TMSGbuf  =  record
      mtype  :  longint;
      mtext  :  array[0..0]  of  char;
   end;


The TMSGbuf record is a record containing the data of a record.  you should never use this
record directly, instead you should make your own record that follows the structure of the
TMSGbuf record, but that has a size that is big enough to accomodate your messages.  The
mtype field should always be present, and should always be filled.


Type
   PMSGinfo  =  ^TMSGinfo;
   TMSGinfo  =  record
      msgpool  :  Longint;
      msgmap    :  Longint;
      msgmax    :  Longint;
      msgmnb    :  Longint;
      msgmni    :  Longint;
      msgssz    :  Longint;
      msgtql    :  Longint;
      msgseg    :  Word;
   end;


The  TMSGinfo  record  is  used  internally  by  the  message  queue  system,  and  should  not  be
used by the programmer directly.


Type
   PSEMid_ds  =  ^PSEMid_ds;
   TSEMid_ds  =  record



                                                                142

_____________________________________________________________10.1.___TYPES,_CONSTANTS_AND_VARIABLES_:______________________________*
 *___
      sem_perm  :  tipc_perm;
      sem_otime  :  longint;
      sem_ctime  :  longint;
      sem_base               :  pointer;
      sem_pending          :  pointer;
      sem_pending_last  :  pointer;
      undo                      :  pointer;
      sem_nsems  :  word;
   end;


The TSEMid__ ds structure is returned by the semctl (149) call, and contains all data concern-
ing a semahore.


Type
   PSEMbuf  =  ^TSEMbuf;
   TSEMbuf  =  record
      sem_num  :  word;
      sem_op    :  integer;
      sem_flg  :  integer;
   end;


The TSEMbuf record us use in the semop (148) call, and is used to specify which operations
you want to do.


Type
   PSEMinfo  =  ^TSEMinfo;
   TSEMinfo  =  record
      semmap  :  longint;
      semmni  :  longint;
      semmns  :  longint;
      semmnu  :  longint;
      semmsl  :  longint;
      semopm  :  longint;
      semume  :  longint;
      semusz  :  longint;
      semvmx  :  longint;
      semaem  :  longint;
   end;


The TSEMinfo record is used internally by the semaphore system, and should not be used
directly.


Type
   PSEMun  =  ^TSEMun;
   TSEMun  =  record
    case  longint  of
         0  :  (  val  :  longint  );
         1  :  (  buf  :  PSEMid_ds  );
         2  :  (  arr  :  PWord  );
         3  :  (  padbuf  :  PSeminfo  );
         4  :  (  padpad  :  pointer  );
    end;


The TSEMun variant record (actually a C union) is used in the semctl (149) call.



                                                                143

                 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 10.2          Functions  and  procedures



                 10.2.1        ftok

Declaration:      Function  ftok  (Path  :    String;  ID  :  char)  :    TKey;

Description:      ftok returns a key that can be used in a semget (148),shmget (153) or msgget (144) call to
                 access a new or existing IPC resource.

                 Path is the name of a file in the file system, ID is a character of your choice.  The ftok call
                 does  the  same  as  it's  C  couterpart,  so  a  pascal  program  and  a  C  program  will  access  the
                 same resource if they use the same Path and ID

       Errors:    ftok returns -1 if the file in Path doesn't exist.

     See also:    semget (148),shmget (153),msgget (144)


                 For an example, see msgctl (145), semctl (149), shmctl (154).
                 10.2.2        msgget

Declaration:      Function  msgget(key:    TKey;  msgflg:longint):longint;

Description:      msgget returns the ID of the message queue described by key.  Depending on the flags in
                 msgflg, a new queue is created.

                 msgflg can have one or more of the following values (combined by ORs):

                 IPC___CREAT          The queue is created if it doesn't already exist.

                 IPC___EXCL        If  used  in  combination  with  IPC__ CREAT,  causes  the  call  to  fail  if  the  queue
                       already exists.  It cannot be used by itself.

                 Optionally, the flags can be ORed with a permission mode, which is the same mode that can
                 be used in the file system.

       Errors:    On error, -1 is returned, and IPCError is set.

     See also:    ftok (144),msgsnd (144), msgrcv (145), msgctl (145), semget (2)


                 For an example, see msgctl (145).
                 10.2.3        msgsnd

Declaration:      Function  msgsnd(msqid:longint;  msgp:    PMSGBuf;  msgsz:    longint;  msgflg:longint):
                 Boolean;

Description:      msgsend sends a message to a message queue with ID msqid.  msgp is a pointer to a message
                 buffer, that should be based on the TMsgBuf type.  msgsiz is the size of the message (NOT
                 of the message buffer record !)

                 The msgflg can have a combination of the following values (ORed together):

                 0No special meaning.  The message will be written to the queue.  If the queue is full, then
                       the process is blocked.

                 IPC___NOWAIT            If the queue is full, then no message is written, and the call returns imme-
                       diatly.

                 The function returns True if the message was sent successfully, False otherwise.



                                                                                 144

                 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    In case of error, the call returns False, and IPCerror is set.

     See also:    msgget (144), msgrcv (145), seefmsgctl


                 For an example, see msgctl (145).
                 10.2.4        msgrcv

Declaration:      Function  msgrcv(msqid:longint;  msgp:    PMSGBuf;  msgsz:    longint;  msgtyp:longint;
                 msgflg:longint):    Boolean;

Description:      msgrcv retrieves a message of type msgtyp from the message queue with ID msqid.  msgtyp
                 corresponds to the mtype field of the TMSGbuf record.  The message is stored in the MSGbuf
                 structure pointed to by msgp.

                 The msgflg parameter can be used to control the behaviour of the msgrcv call.  It consists
                 of an ORed combination of the following flags:

                 0No special meaning.

                 IPC___NOWAIT            if  no  messages  are  available,  then  the  call  returns  immediatly,  with  the
                       ENOMSG error.

                 MSG___NOERROR                If the message size is wrong (too large), no error is generated, instead
                       the message is truncated.  Normally, in such cases, the call returns an error (E2BIG)

                 The function returns True if the message was received correctly, False otherwise.

       Errors:    In case of error, False is returned, and IPCerror is set.

     See also:    msgget (144), msgsnd (144), msgctl (145)


                 For an example, see msgctl (145).
                 10.2.5        msgctl

Declaration:      Function  msgctl(msqid:longint;  cmd:    longint;  buf:    PMSQid__ ds):    Boolean;

Description:      msgctl performs various operations on the message queue with id ID. Which operation is
                 performed, depends on the cmd parameter, which can have one of the following values:

                 IPC___STAT        In  this  case,  the  msgctl  call  fills  the  TMSQid__ ds  structure  with  information
                       about the message queue.

                 IPC___SET      in this case, the msgctl call sets the permissions of the queue as specified in the
                       ipc__ perm record inside buf.

                 IPC___RMID         If this is specified, the message queue will be removed from the system.

                 buf contains the data that are needed by the call.  It can be Nil in case the message queue
                 should be removed.

                 The function returns True if successfull, False otherwise.

       Errors:    On error, False is returned, and IPCerror is set accordingly.

     See also:    msgget (144), msgsnd (144), msgrcv (145)

                                                                                 145

 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________________________*
 *____
________________________________________________________________________________________________________________________________
 program       m s g t o o l;


 Uses     i p c;


 Type
    PMyMsgBuf        =  ^  TMyMsgBuf       ;
    TMyMsgBuf        =   r e c o r d
        mtype     :   L o n g i n t;
        mtext     :   s t r i n g[ 2 5 5 ] ;
    end   ;


 Procedure        D o E r r o r ( Const     Msg    :   s t r i n g) ;


 b e g i n
    W r i t e l n ( msg  , ' r e t u r n e d|_|an|_|e r r o|r_|: |_|',i p c e r r)o;r
    h a l t( 1 ) ;
 end  ;


 Procedure        SendMessage          ( I d  :   L o n g i n t;
                                         Var    Buf    :  TMyMsgBuf       ;
                                         MType     :   L o n g i n t;
                                         Const     MText      :  S t r i n g) ;


 b e g i n
    W r i t e l n ( ' S e n d i n g|_|message   . ') ;
    Buf   .mtype    := mtype    ;
    Buf   .Mtext    := mtext    ;
    I f  not    msgsnd     ( I d, PMsgBuf     ( @Buf   ) , 2 5 6 , 0 )then
        D o E r r o r('msgsnd     ' ) ;
 end  ;


 Procedure        ReadMessage          ( ID   :   L o n g i n t;
                                         Var    Buf    :  TMyMsgBuf       ;
                                         MType     :   l o n g i n t) ;


 b e g i n
    W r i t e l n ( ' R e a d i n g|_|message   . ') ;
    Buf   .MType    := MType    ;
    I f  msgrcv     ( ID , PMSGBuf     ( @Buf   ) , 2 5 6 ,mtype   , 0 )  then
        W r i t e l n( ' Type    |_|: |_|',b u.fmtype    ,' |_|Text  |_|: |_|',b u f.mtext   )
    e l s e
        D o E r r o r( ' msgrcv     ' ) ;
 end  ;


 Procedure        RemoveQueue          (   ID   :  L o n g i n t) ;


 b e g i n
    I f   m s g c t l(  i d,IPC__RMID      ,N i l )  then
        W r i t e l n( ' Removed     |_|Queue   |_|w i t h|_|i'd,I d ) ;
 end  ;


 Procedure        ChangeQueueMode             ( ID , mode     :  l o n g i n t) ;


 Var    QueueDS       :  TMSQid__ds      ;


 b e g i n
    I f  Not     m s g c t l( I d ,IPC__STAT      ,@QueueDS      )   then
                                                                 146

__________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES_________________________*
 *___
       D o E r r o r( ' m s g c t l|_|: |_|s t a't) ;
   W r i t e l n ( ' Old  |_|p e r m i s s i o n|s_|: |_|',QueueDS  .msg __perm    . mode   ) ;
   QueueDS      .msg __perm    . mode   := Mode   ;
   i f   m s g c t l( ID  ,IPC__SET     ,@QueueDS       )  then
       W r i t e l n( ' New  |_|p e r m i s s i o n|s_|: |_|',QueueDS  . msg __perm    .mode    )
   e l s e
     D o E r r o r ( ' m s g c t l|_|:I|_|PC__SET ' ) ;
end  ;


p r o c e d u r eu s a g e;


b e g i n
   W r i t e l n ( ' Usage    |_|: |_|m s g t o|o_l|s(end) |_||_||_||_|<t y>p|e_|<t e x>t|_|(max  |_|2 5 5c|_|h a r a c t e r)s') ;
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|r(e)c|e_i|v<et>y'p)e;
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|d(e)l'e)t;e
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|m(ode)d|_|<e|c_i|mmaolde>') ;
   h a l t( 1 ) ;
end  ;


F u n c t i o nS t r T o I n t ( S  :   S t r i n g) :  l o n g i n t;


Var   M   :   l o n g i n t;
      C   :   I n t e g e r;


b e g i n
   v a l  ( S ,M , C ) ;
   I f  C <>0    Then     D o E r r o r ( 'S t r T o I n t|_|: |_|'+S) ;
   S t r T o I n t:=M ;
end  ;


Var
   Key    :   TKey   ;
   ID     :   l o n g i n t;
   Buf    :   TMyMsgBuf      ;


b e g i n
   I f  Paramcount        <1   then     Usage    ;
   key    :=  Ftok   ( ' . ',' M ' ) ;
   ID  := msgget     (key   ,IPC__CREAT        or   4 3 8 ) ;
   I f  ID  <0   then     D o E r r o r ( 'MsgGet     ' ) ;
   Case     upCase    ( Paramstr      ( 1 ) [ 1 ] ) of
     ' S '  :   I f  ParamCount       <>3    then
                   Usage
                e l s e
                   SendMessage          ( i d, Buf  , S t r T o I n t(Paramstr      ( 2 ) ) ,p a r a m s t(r3 ) ) ;
     'R  '  :   I f  ParamCount       <>2    then
                   Usage
                e l s e
                   ReadMessage          ( i d, b u f, s t r t o i n t(Paramstr      ( 2 ) ) ) ;
     'D  '  :   I f  ParamCount       <>1    then
                   Usage
                e l s e
                   RemoveQueue          ( ID ) ;
     'M  '  :   I f  ParamCount       <>2    then
                   Usage
                e l s e
                   ChangeQueueMode             ( i d, s t r t o i n t(p a r a m s t r( 2 ) ) ) ;
     e l s e
                                                                147

                 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                         Usage
                      end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 10.2.6        semget

Declaration:      Function  semget(key:Tkey;  nsems:longint;  semflg:longint):    longint;

Description:      msgget returns the ID of the semaphore set described by key.  Depending on the flags in
                 semflg, a new queue is created.

                 semflg can have one or more of the following values (combined by ORs):

                 IPC___CREAT          The queue is created if it doesn't already exist.

                 IPC___EXCL        If used in combination with IPC__ CREAT, causes the call to fail if the set already
                       exists.  It cannot be used by itself.

                 Optionally, the flags can be ORed with a permission mode, which is the same mode that can
                 be used in the file system.

                 if a new set of semaphores is created, then there will be nsems semaphores in it.

       Errors:    On error, -1 is returned, and IPCError is set.

     See also:    ftok (144), semop (148), semctl (149)
                 10.2.7        semop

Declaration:      Function  semop(semid:longint;  sops:    pointer;  nsops:    cardinal):    Boolean;

Description:      semop performs a set of operations on a message queue.  sops points to an array of type
                 TSEMbuf.  The array should contain nsops elements.

                 The fields of the TSEMbuf structure

                    TSEMbuf  =  record
                       sem_num  :  word;
                       sem_op    :  integer;
                       sem_flg  :  integer;

                 should be filled as follows:

                 sem___num      The  number  of  the  semaphore  in  the  set  on  which  the  operation  must  be  per-
                       formed.

                 sem___op    The operation to be performed.  The operation depends on the sign of  sem__ op

                           1.A positive number is simply added to the current value of the semaphore.
                           2.If 0 (zero) is specified, then the process is suspended until the specified semaphore
                             reaches zero.
                           3.If  a  negative  number  is  specified,  it  is  substracted  from  the  current  value  of  the
                             semaphore.  If the value would become negative then the process is suspended until
                             the value becomes big enough, unless IPC__ NOWAIT is specified in the sem__ flg.

                 sem___flg   Optional flags:  if  IPC__ NOWAIT is specified,  then the calling process will never be
                       suspended.

                 The function returns True if the operations were successful, False otherwise.

       Errors:    In case of error, False is returned, and IPCerror is set.

     See also:    semget (148), semctl (149)



                                                                                 148

                 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 10.2.8        semctl

Declaration:      Function  semctl(semid:longint;  semnum:longint;  cmd:longint;  var  arg:    tsemun):
                 longint;

Description:      semctl performs various operations on the semaphore semnum w ith semaphore set id ID.

                 The  arg  parameter  supplies  the  data  needed  for  each  call.   This  is  a  variant  record  that
                 should be filled differently, according to the command:


                 Type
                    TSEMun  =  record
                     case  longint  of
                          0  :  (  val  :  longint  );
                          1  :  (  buf  :  PSEMid_ds  );
                          2  :  (  arr  :  PWord  );
                          3  :  (  padbuf  :  PSeminfo  );
                          4  :  (  padpad  :  pointer  );
                     end;


                 Which  operation  is  performed,  depends  on  the  cmd  parameter,  which  can  have  one  of  the
                 following values:

                 IPC___STAT        In  this  case,  the  arg  record  should  have  it's  buf  field  set  to  the  address  of  a
                       TSEMid__ ds  record.  The  semctl  call  fills  this  TSEMid__ ds  structure  with  information
                       about the semaphore set.

                 IPC___SET      In  this  case,  the  arg  record  should  have  it's  buf  field  set  to  the  address  of  a
                       TSEMid__ ds record.  The semctl call sets the permissions of the queue as specified in
                       the ipc__ perm record.

                 IPC___RMID         If this is specified, the semaphore set is removed from from the system.

                 GETALL        In this case, the arr field of arg should point to a memory area where the values of
                       the semaphores will be stored.  The size of this memory area is SizeOf(Word)*  Number
                       of  semaphores  in  the  set.   This  call  will  then  fill  the  memory  array  with  all  the
                       values of the semaphores.

                 GETNCNT           This will fill the val field of the arg union with the bumber of processes waiting
                       for resources.

                 GETPID        semctl returns the process ID of the process that performed the last semop (148)
                       call.

                 GETVAL        semctl returns the value of the semaphore with number semnum.

                 GETZCNT          semctl returns the number of processes waiting for semaphores that reach value
                       zero.

                 SETALL       In  this  case,  the  arr  field  of  arg  should  point  to  a  memory  area  where  the
                       values  of  the  semaphores  will  be  retrieved  from.   The  size  of  this  memory  area  is
                       SizeOf(Word)*  Number  of  semaphores  in  the  set.  This call will then set the val-
                       ues of the semaphores from the memory array.

                 SETVAL        This will set the value of semaphore semnum to the value in the val field of the
                       arg parameter.

                 The function returns -1 on error.

       Errors:    The function returns -1 on error, and IPCerror is set accordingly.

     See also:    semget (148), semop (148)

                                                                                 149

 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________________________*
 *____
________________________________________________________________________________________________________________________________
 Program       s e m t o o l;


 {  Program       to    d e m o n s t r a tt h e  u s e  o f  s e m a p h o r e s}


 Uses     i p c;


 Const     MaxSemValue          =  5 ;


 Procedure        D o E r r o r ( Const     Msg    :   S t r i n g) ;


 b e g i n
    W r i t e l n ( ' E r r o r|_|: |_|',msg, ' |_|Code  |_|: |_|',I P C e r r o)r;
    Halt   ( 1 ) ;
 end  ;


 F u n c t i o n g e t s e m v a l( ID , Member      :   l o n g i n t)  :  l o n g i n t;


 Var    S  :  TSEMun     ;


 b e g i n
    GetSemVal       := SemCtl     ( i d, member    , GETVAL     ,S ) ;
 end  ;


 Procedure        D i s p V a l ( ID , member      :   l o n g i n t) ;


 b e g i n
    w r i t e l n ( ' V a l u e|_|f o|r_|member   |_|',member    , ' |_|i s|_|',GetSemVal      ( ID , Member     ) ) ;
 end  ;


 F u n c t i o nGetMemberCount            ( ID    :  L o n g i n t)  :  l o n g i n t;


 Var    o p t s :   TSEMun    ;
        semds     :   TSEMid __ds    ;


 b e g i n
    o p t s. b u f:=  @semds    ;
    I f   s e m c t l(I d, 0 ,IPC__STAT     , o p t s)<>-1     then
        GetMemberCount          :=  semds   . sem __nsems
    e l s e
        GetMemberCount          :=-1;
 end  ;


 F u n c t i o nOpenSem       ( Key    :  TKey    )  :   L o n g i n t;


 b e g i n
    OpenSem     :=  semget    ( Key   , 0 , 4 3 8 ) ;
    I f  OpenSem     =-1     then
        D o E r r o r( ' OpenSem     ' ) ;
 end  ;


 F u n c t i o nCreateSem         ( Key    :  TKey   ;  Members       :   L o n g i n t)  :  L o n g i n t;


 Var    Count     :   L o n g i n t;
        Semopts       :  TSemun     ;


 b e g i n
    I f  members     > semmsl       then
                                                                 150

__________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES_________________________*
 *___
       D o E r r o r( ' S o r r y, |_|maximum    |_|number   |_|o f|_|s e m a p h o r|e_s|i|n_|s e|t_|e x c e e d'e)d;
   W r i t e l n ( ' T r y i n g|_|to|_|c r e a t|e_|a|_|new|_|s e m a p h o r|e_|s e|t_|w i|t_h|',members    ,' |_|members    . ' *
 *) ;
   CreateSem       := semget     ( key  , members     ,IPC__CREAT        or   IPC __Excl      or   4 3 8 ) ;
   I f  CreateSem       =-1    then
       D o E r r o r( ' Semaphore       |_|s e t|_|a l r e a d|y_|e x i s.t's) ;
   Semopts      .v a l:=  MaxSemValue        ;   {  I n i t i a l v a l u e  o f  s e m a p h o r e s}
   For    Count    :=0    to   Members     -1   do
       s e m c t l(CreateSem       ,c o u n t, s e t v a l,s e m o p t s) ;
end  ;


Procedure        lockSem       ( ID , Member     :  L o n g i n t) ;


Var    l o c k :   TSEMbuf     ;


b e g i n
   With     l o c k  do
       b e g i n
       sem__num    : = 0 ;
       sem __op  :=-1;
       s e m __f l g:=IPC__NOWAIT       ;
       end  ;
     i f  ( member    <0)    or   ( member    >  GetMemberCount          ( ID ) - 1 )  then
         D o E r r o r( ' s e m a p h o r e|_|member  |_|out |_|o f|_|r a n g'e) ;
     i f  g e t s e m v a l(ID , member    )=0    then
         D o E r r o r( ' Semaphore       |_|r e s o u r c e|s_|e x h a u s t|e_d|(no|_|l o c)k') ;
     l o c k.sem__num     := member     ;
     W r i t e l n ( 'A t t e m p t i n g|_|to|_|l o c|k_|member  |_|',member     ,  ' |_|o f|_|s e m a p h o r|e_|',ID) ;
     i f  not    semop    ( I d, @ l o c k, 1 )  then
         D o E r r o r( ' Lock   |_|f a i l e'd)
     e l s e
         W r i t e l n( ' Semaphore       |_|r e s o u r c e|s_|d e c r e m e n t|e_d|by|_|one') ;
     d i s p v a l(ID , Member     ) ;
end  ;


Procedure        UnlockSem        ( ID  ,Member     :   L o n g i n t) ;


Var    U n l o c k :  TSEMbuf      ;


b e g i n
   With     U n l o c k do
       b e g i n
       sem__num    : = 0 ;
       sem __op  : = 1 ;
       s e m __f l g:=IPC__NOWAIT       ;
       end  ;
     i f  ( member    <0)    or   ( member    >  GetMemberCount          ( ID ) - 1 )  then
         D o E r r o r( ' s e m a p h o r e|_|member  |_|out |_|o f|_|r a n g'e) ;
     i f  g e t s e m v a l(ID , member    )=  MaxSemValue          then
         D o E r r o r( ' Semaphore       |_|not |_|l o c k e'd) ;
     U n l o c k.sem__num    :=  member    ;
     W r i t e l n ( 'A t t e m p t i n g|_|to|_|u n l o c|k_|member  |_|',member    ,   ' |_|o f|_|s e m a p h o|r_e|',ID) ;
     i f  not    semop    ( I d, @ u n l o c k, 1 ) then
         D o E r r o r( ' U n l o c k|_|f a i l e'd)
     e l s e
         W r i t e l n( ' Semaphore       |_|r e s o u r c e|s_|i n c r e m e n t|e_d|by|_|one') ;
     d i s p v a l(ID , Member     ) ;
end  ;


                                                                151

__________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES_________________________*
 *___
Procedure        RemoveSem        ( ID    :  l o n g i n t) ;


v a r  S  :   TSemun    ;


b e g i n
   I f   s e m c t l(I d, 0 ,IPC__RMID     , s )<>-1     then
       W r i t e l n( ' Semaphore       |_|removed    ' )
   e l s e
       D o E r r o r( ' Couldn     '' t |_|remove   |_|s e m a p h o r'e) ;
end  ;



Procedure        ChangeMode         ( ID  ,Mode     :   l o n g i n t) ;


Var    r c  :   l o n g i n t;
       o p t s :   TSEMun    ;
       semds     :   TSEMid __ds    ;


b e g i n
   o p t s. b u f:=  @semds    ;
   I f  not     s e m c t l( I d , 0 ,IPC__STAT     , o p t s)<>-1     then
       D o E r r o r( ' Couldn     '' t |_|s t a t|_|s e m a p h o'r)e;
   W r i t e l n ( ' Old  |_|p e r m i s s i o n|s_|were|_|: |_|',semds  . sem __perm    .mode    ) ;
   semds    . sem __perm    .mode   :=  mode   ;
   I f   s e m c t l(i d, 0 ,IPC__SET     ,o p t s)<>-1      then
       W r i t e l n( ' S e t|_|p e r m i s s i o n|s_|to|_|',mode  )
   e l s e
       D o E r r o r( ' Couldn     '' t |_|s e t|_|p e r m i s s i o'n)s;
end  ;


Procedure        P r i n t S e m ( ID   :   l o n g i n t) ;


Var    I ,c n t  :   l o n g i n t;


b e g i n
   c n t:=  g e t m e m b e r c o u n(tID ) ;
   W r i t e l n ( ' Semaphore       |_|',ID , ' |_|has |_|',c n t, ' |_|Members   ' ) ;
   For    I :=0    to   c n t-1   Do
       D i s p V a l(i d, i ) ;
end  ;


Procedure        USage    ;


b e g i n
   W r i t e l n ( ' Usage    |_|: |_|s e m t o|o_l|c(r e a t)e|_|<c o u n t>') ;
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|l(ock)m|_|<ember>') ;
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|u(n)l|o_c|k<member>') ;
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|d(e)l'e)t;e
   W r i t e l n ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|m(ode)m|_|<ode>') ;
   h a l t( 1 ) ;
end  ;


F u n c t i o nS t r T o I n t ( S  :   S t r i n g) :  l o n g i n t;


Var   M   :   l o n g i n t;
      C   :   I n t e g e r;


b e g i n
                                                                152

                 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    v a l  ( S ,M , C ) ;
                    I f  C <>0    Then     D o E r r o r ( 'S t r T o I n t|_|: |_|'+S) ;
                    S t r T o I n t:=M ;
                 end  ;


                 Var    Key    :  TKey   ;
                        ID   :   L o n g i n t;


                 b e g i n
                    I f  ParamCount        <1   then     USage    ;
                    key  :=  f t o k( ' . ', 's ' ) ;
                    Case     UpCase    ( Paramstr      ( 1 ) [ 1 ] ) of
                      'C  '  :  b e g i n
                                 i f  paramcount       <>2    then     u s a g e;
                                CreateSem         ( key  , s t r t o i n t(p a r a m s t(r2 ) ) ) ;
                                end   ;
                      ' L '  :  b e g i n
                                 i f  paramcount       <>2    then     u s a g e;
                                ID  := OpenSem       ( key  ) ;
                                LockSem       ( ID  , s t r t o i n(tp a r a m s t r( 2 ) ) ) ;
                                end   ;
                      'U  '  :  b e g i n
                                 i f  paramcount       <>2    then     u s a g e;
                                ID  := OpenSem       ( key  ) ;
                                UnLockSem         ( ID , s t r t o i n t(p a r a m s t r( 2 ) ) ) ;
                                end   ;
                      'M  '  :  b e g i n
                                 i f  paramcount       <>2    then     u s a g e;
                                ID  := OpenSem       ( key  ) ;
                                ChangeMode         ( ID  , s t r t o i n t(p a r a m s t(r2 ) ) ) ;
                                end   ;
                      'D  '  :  Begin
                                ID  := OpenSem      (Key   ) ;
                                RemoveSem       ( I d ) ;
                                end   ;
                      'P  '  :  b e g i n
                                ID  := OpenSem      (Key   ) ;
                                P r i n t S e m(I d ) ;
                                end   ;
                    e l s e
                        Usage
                    end   ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 10.2.9        shmget

Declaration:      Function  shmget(key:    Tkey;  Size:longint;  flag:longint):longint;

Description:      shmget returns the ID of a shared memory block, described by key.  Depending on the flags
                 in flag, a new memory block is created.

                 flag can have one or more of the following values (combined by ORs):

                 IPC___CREAT          The queue is created if it doesn't already exist.

                 IPC___EXCL        If  used  in  combination  with  IPC__ CREAT,  causes  the  call  to  fail  if  the  queue
                       already exists.  It cannot be used by itself.


                                                                                 153

                 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Optionally, the flags can be ORed with a permission mode, which is the same mode that can
                 be used in the file system.

                 if a new memory block is created, then it will have size Size semaphores in it.

       Errors:    On error, -1 is returned, and IPCError is set.

     See also:
                 10.2.10         shmat

Declaration:      Function  shmat  (shmid:longint;  shmaddr:pchar;  shmflg:longint):pchar;

Description:      shmat attaches a shared memory block with identified shmid to the current process.  The
                 function returns a pointer to the shared memory block.

                 If  shmaddr is Nil, then the system chooses a free unmapped memory region, as high up in
                 memory space as possible.

                 If  shmaddr  is  non-nil,  and  SHM__ RND  is  in  shmflg,  then  the  returned  address  is  shmaddr,
                 rounded down to SHMLBA. If SHM__ RND is not specified, then shmaddr must be a page-aligned
                 address.

                 The parameter shmflg can be used to control the behaviour of the shmat call.  It consists of
                 a ORed combination of the following costants:

                 SHM___RND          The suggested address in shmaddr is rounded down to SHMLBA.

                 SHM___RDONLY              the shared memory is attached for read access only.  Otherwise the mem-
                       ory is attached for read-write.  The process then needs read-write permissions to access
                       the shared memory.

       Errors:    If an error occurs, -1 is returned, and IPCerror is set.

     See also:    shmget (153), shmdt (154), shmctl (154)


                 For an example, see shmctl (154).
                 10.2.11         shmdt

Declaration:      Function  shmdt  (shmaddr:pchar):boolean;

Description:      shmdt  detaches  the  shared  memory  at  address  shmaddr.   This  shared  memory  block  is
                 unavailable to the current process, until it is attached again by a call to shmat (154).

                 The function returns True if the memory block was detached successfully, False otherwise.

       Errors:    On error, False is returned, and IPCerror is set.

     See also:    shmget (153), shmat (154), shmctl (154)
                 10.2.12         shmctl

Declaration:      Function  shmctl(shmid:longint;  cmd:longint;  buf:    pshmid__ ds):    Boolean;

Description:      shmctl  performs  various  operations  on  the  shared  memory  block  identified  by  identifier
                 shmid.

                 The buf parameter points to a TSHMid__ ds record.  The cmd parameter is used to pass which
                 operation is to be performed.  It can have one of the following values :
                                                                                 154

            __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES_____________*
 *_______________
            IPC___STAT        shmctl fills the TSHMid__ ds record that buf points to with the available infor-
                  mation about the shared memory block.

            IPC___SET      applies  the  values  in  the  ipc__ perm  record  that  buf  points  to,  to  the  shared
                  memory block.

            IPC___RMID         the shared memory block is destroyed (after all processes to which the block
                  is attached, have detached from it).

            If successful, the function returns True, False otherwise.

  Errors:    If an error occurs, the function returns False, and IPCerror is set.

See also:    shmget (153), shmat (154), shmdt (154)


           ________________________________________________________________________________________________________________________*
 *________
            Program       s h m t o o l;


            u s e s  i p c, s t r i n g s;


            Const     S e g S i z e =  1 0 0 ;


            v a r  key    :  Tkey   ;
                   shmid    ,c n t r  :   l o n g i n t;
                   s e g p t r :  p c h a r;


            Procedure        USage    ;


            b e g i n
              W r i t e l n( ' Usage    |_|: |_|s h m t o|o_l|w(r i t)e|_|t e x t') ;
              w r i t e l n( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|r(ead))';
              w r i t e l n( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|d(e)l'e)t;e
              w r i t e l n( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_||_||_|m(ode|_|c)h|a_n|gmeode') ;
              h a l t( 1 ) ;
            end  ;


            Procedure        Writeshm        ( ID   :  L o n g i n t;  p t r  :   p c h a r; S   :   s t r i n g) ;


            b e g i n
               s t r p c o p y ( p t r, s ) ;
            end  ;


            Procedure        Readshm     ( ID   :   l o n g i n t;  p t r :   p c h a r) ;


            b e g i n
               W r i t e l n ( ' Read   |_|: |_|',p t r) ;
            end  ;


            Procedure        removeshm        ( ID    :  L o n g i n t) ;


            b e g i n
               s h m c t l ( ID  ,IPC__RMID     , N i l) ;
               w r i t e l n ( ' S h a r e d|_|memory  |_|marked    |_|f o r|_|d e l e t i'o)n;
            end  ;


            Procedure        CHangeMode         ( ID   :   l o n g i n t; mode     :   S t r i n g) ;


            Var   m   :   word   ;
                   code    :   i n t e g e r;
                   d a t a :   TSHMid__ds      ;



                                                                            155

 __________________________________________________________________________10.2.___FUNCTIONS_AND_PROCEDURES________________________*
 *____


 b e g i n
    v a l  ( mode   ,m , code   ) ;
    i f  code   <>0    then
        u s a g e;
    I f  Not     s h m c t l( shmid    , IPC__STAT     , @data   )   then
        b e g i n
        w r i t e l n( ' E r r o r|_|: |_|s h m c t|l_|:,'i p c e r r o)r;
        h a l t( 1 ) ;
        end  ;
    w r i t e l n ( ' Old  |_|p e r m i s s i o n|s_|: |_|',d a t.ashm __perm  . mode   ) ;
    d a t a. shm __perm    .mode   :=  m ;
    I f  Not     s h m c t l( shmid    , IPC__SET    , @data    )  then
        b e g i n
        w r i t e l n( ' E r r o r|_|: |_|s h m c t|l_|:,'i p c e r r o)r;
        h a l t( 1 ) ;
        end  ;
    w r i t e l n ( 'New   |_|p e r m i s s i o n|s_|: |_|',d a t.ashm __perm  . mode   ) ;
 end  ;


 b e g i n
    i f  paramcount        <1   then     u s a g e;
    key    : =   f t o k ( ' . ', 'S ' ) ;
    shmid     : =   shmget    ( key  , s e g s i z e,IPC__CREAT       or   IPC__EXCL       or   4 3 8 ) ;
    I f  shmid    =-1    then
        b e g i n
        W r i t e l n( ' S h a r e d|_|memory   |_|e x i s t.s|_|Opening    |_|as|_|c l i e n't) ;
        shmid     : =  shmget     ( key  , s e g s i z e, 0 ) ;
        I f  shmid     =  -1    then
           b e g i n
           W r i t e l n ( ' shmget    |_|: |_|E r r o|r_|!,'i p c e r r o)r;
           h a l t( 1 ) ;
           end
        end
    e l s e
        W r i t e l n( ' C r e a t i n g|_|new|_|s h a r e|d_|memory   |_|segment    . ') ;
    s e g p t r:= shmat    ( shmid   , n i l , 0 ) ;
    i f   l o n g i n t(s e g p t r)=-1    then
        b e g i n
        W r i t e l n( ' Shmat    |_|: |_|e r r o|r_|!,'i p c e r r o)r;
        h a l t( 1 ) ;
        end  ;
    case     upcase    ( p a r a m s t r( 1 ) [ 1 ] )of
        'W '   :  w r i t e s h m ( shmid   , s e g p t r,p a r a m s t r( 2 ) ) ;
        'R '   :  readshm       ( shmid    ,s e g p t r) ;
        'D '   :  removeshm       ( shmid   ) ;
        'M '   :  changemode         ( shmid    , p a r a m s t r( 2 ) ) ;
    e l s e
        b e g i n
        w r i t e l n( p a r a m s t r( 1 ) ) ;
        u s a g e;
        end  ;
    end   ;
_end__._________________________________________________________________________________________________________________________



                                                                 156


Chapter   11


The   LINUX   unit.



This chapter describes the LINUX unit for Free Pascal.  The unit was written by Micha"el
van  Canneyt.  It  works  only  on  the  Linux  operating  system.  This  chapter  is  divided  in  3
sections:


    o  The first section lists all constants, types and variables, as listed in the interface section
       of the LINUX unit.

    o  The second section gives and overview of all available functions, grouped by category.

    o  The third section describes all procedures and functions in the LINUX unit.
11.1          Type,  Variable  and  Constant  declarations



11.1.1        Types

PGlob and TGlob are 2 types used in the Glob (204) function:


PGlob  =  ^TGlob;
TGlob  =  record
   Name  :  PChar;
   Next  :  PGlob;
   end;


The following types are used in the signal-processing procedures.


tfpreg  =  record
   significand:  array[0..3]  of  word;
   exponent:  word;
end;


pfpstate  =  ^tfpstate;
tfpstate  =  record
   cw,  sw,  tag,  ipoff,  cssel,  dataoff,  datasel:  cardinal;
   st:  array[0..7]  of  tfpreg;
   status:  cardinal;
end;


PSigContextRec  =  ^SigContextRec;



                                                            157

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
SigContextRec  =  record
   gs,  __gsh:  word;
   fs,  __fsh:  word;
   es,  __esh:  word;
   ds,  __dsh:  word;
   edi:  cardinal;
   esi:  cardinal;
   ebp:  cardinal;
   esp:  cardinal;
   ebx:  cardinal;
   edx:  cardinal;
   ecx:  cardinal;
   eax:  cardinal;
   trapno:  cardinal;
   err:  cardinal;
   eip:  cardinal;
   cs,  __csh:  word;
   eflags:  cardinal;
   esp_at_signal:  cardinal;
   ss,  __ssh:  word;
   fpstate:  pfpstate;
   oldmask:  cardinal;
   cr2:  cardinal;
   end;


The above records contain information about the processor state and process state at the
moment a signal is sent to your program.

The records below are used in catching signals.


TSigAction  =  procedure(Sig:  Longint;  SigContext:  SigContextRec);cdecl;
SignalHandler     =  Procedure  (  Sig  :  Integer);cdecl;


PSignalHandler    =  SignalHandler;
SignalRestorer    =  Procedure;cdecl;
PSignalrestorer  =  SignalRestorer;
SigActionRec  =  packed  record
   Handler    :  record
      case  byte  of
         0:  (Sh:  SignalHandler);
         1:  (Sa:  TSigAction);
      end;
   Sa_Mask        :  SigSet;
   Sa_Flags       :  Longint;
   Sa_restorer  :  SignalRestorer;  {  Obsolete  -  Don't  use  }
end;
   PSigActionRec  =  ^SigActionRec;


Stat is used to store information about a file.  It is defined in the syscalls unit.


   stat  =  record
        dev       :  word;
        pad1     :  word;
        ino       :  longint;
        mode     :  word;



                                                                158

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
        nlink    :  word;
        uid       :  word;
        gid       :  word;
        rdev     :  word;
        pad2     :  word;
        size     :  longint;
        blksze  :  Longint;
        blocks  :  Longint;
        atime    :  Longint;
        unused1  :  longint;
        mtime     :  Longint;
        unused2  :  longint;
        ctime     :  Longint;
        unused3  :  longint;
        unused4  :  longint;
        unused5  :  longint;
        end;
Statfs is used to store information about a filesystem.  It is defined in the syscalls unit.


    statfs  =  record
        fstype     :  longint;
        bsize       :  longint;
        blocks     :  longint;
        bfree       :  longint;
        bavail     :  longint;
        files       :  longint;
        ffree       :  longint;
        fsid        :  longint;
        namelen    :  longint;
        spare       :  array  [0..6]  of  longint;
        end


Dir  and  PDir are used in the OpenDir (214) and ReadDir (217) functions.


   TDir  =record
      fd        :  integer;
      loc       :  longint;
      size     :  integer;
      buf       :  pdirent;
      nextoff:  longint;
      dd_max  :  integer;
      lock     :  pointer;
   end;
   PDir  =^TDir;


Dirent,  PDirent are used in the ReadDir (217) function to return files in a directory.


 PDirent  =  ^Dirent;
 Dirent  =  Record
    ino,
    off       :  longint;
    reclen  :  word;



                                                                159

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
    name     :  string[255]
 end;


Termio and Termios are used with iotcl() calls for terminal handling.


Const    NCCS  =  19;
           NCC  =  8;


Type  termio  =  record
c_iflag,{  input  mode  flags  }
c_oflag,{  output  mode  flags  }
c_cflag,{  control  mode  flags  }
c_lflag  :  Word;  {  local  mode  flags  }
c_line  :  Word;  {  line  discipline  -  careful,  only  High  byte  in  use}
c_cc  :  array  [0..NCC-1]  of  char;  {  control  characters  }
end;
termios  =  record
   c_iflag,                       {  input  mode  flags  }
   c_oflag,                       {  output  mode  flags  }
   c_cflag,                       {  control  mode  flags  }
   c_lflag  :  Cardinal;  {  local  mode  flags  }
   c_line  :  char;                 {  line  discipline  }
   c_cc  :  array  [0..NCCS-1]  of  char;          {  control  characters  }
end;


Utimbuf is used in the Utime (233) call to set access and modificaton time of a file.


utimbuf  =  record
   actime,modtime  :  Longint;
   end;


For the Select (220) call, the following 4 types are needed:


FDSet  =  Array  [0..31]  of  longint;
PFDSet  =  ^FDSet;
TimeVal  =  Record
    sec,usec  :  Longint;
end;
PTimeVal  =  ^TimeVal;


The Uname (232) function uses the utsname to return information about the current kernel
:


utsname  =record
   sysname,nodename,release,
   version,machine,domainname  :  Array[0..64]  of  char;
end;


Its elements are null-terminated C style strings, you cannot access them directly !
11.1.2        Variables

Linuxerror is the variable in which the procedures in the linux unit report errors.
                                                                160

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
LinuxError  :  Longint;


StdErr  Is  a  Text  variable,  corresponding  to  Standard  Error  or  diagnostic  output.   It  is
connected to file descriptor 2.  It can be freely used, and will be closed on exit.


StdErr  :  Text;
11.1.3        Constants

Constants for setting/getting process priorities :


         Prio_Process  =  0;
         Prio_PGrp       =  1;
         Prio_User       =  2;


For testing access rights:


         R_OK  =  4;
         W_OK  =  2;
         X_OK  =  1;
         F_OK  =  0;


For signal handling functions :


         SA_NOCLDSTOP  =  1;
         SA_SHIRQ       =  $04000000;
         SA_STACK       =  $08000000;
         SA_RESTART     =  $10000000;
         SA_INTERRUPT  =  $20000000;
         SA_NOMASK       =  $40000000;
         SA_ONESHOT     =  $80000000;


         SIG_BLOCK     =  0;
         SIG_UNBLOCK  =  1;
         SIG_SETMASK  =  2;
         SIG_DFL  =  0  ;
         SIG_IGN  =  1  ;
         SIG_ERR  =  -1;


         SIGHUP  =  1;
         SIGINT  =  2;
         SIGQUIT  =  3;
         SIGILL  =  4;
         SIGTRAP  =  5;
         SIGABRT  =  6;
         SIGIOT  =  6;
         SIGBUS  =  7;
         SIGFPE  =  8;
         SIGKILL  =  9;
         SIGUSR1  =  10;
         SIGSEGV  =  11;
         SIGUSR2  =  12;
         SIGPIPE  =  13;
         SIGALRM  =  14;



                                                                161

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
         SIGTERM  =  15;
         SIGSTKFLT  =  16;
         SIGCHLD  =  17;
         SIGCONT  =  18;
         SIGSTOP  =  19;
         SIGTSTP  =  20;
         SIGTTIN  =  21;
         SIGTTOU  =  22;
         SIGURG  =  23;
         SIGXCPU  =  24;
         SIGXFSZ  =  25;
         SIGVTALRM  =  26;
         SIGPROF  =  27;
         SIGWINCH  =  28;
         SIGIO  =  29;
         SIGPOLL  =  SIGIO;
         SIGPWR  =  30;
         SIGUNUSED  =  31;


For file control mechanism :


         F_GetFd    =  1;
         F_SetFd    =  2;
         F_GetFl    =  3;
         F_SetFl    =  4;
         F_GetLk    =  5;
         F_SetLk    =  6;
         F_SetLkW  =  7;
         F_GetOwn  =  8;
         F_SetOwn  =  9;


For Terminal handling :


    TCGETS  =  $5401  ;
    TCSETS  =  $5402  ;
    TCSETSW  =  $5403  ;
    TCSETSF  =  $5404  ;
    TCGETA  =  $5405  ;
    TCSETA  =  $5406  ;
    TCSETAW  =  $5407  ;
    TCSETAF  =  $5408  ;
    TCSBRK  =  $5409  ;
    TCXONC  =  $540A  ;
    TCFLSH  =  $540B  ;
    TIOCEXCL  =  $540C  ;
    TIOCNXCL  =  $540D  ;
    TIOCSCTTY  =  $540E  ;
    TIOCGPGRP  =  $540F  ;
    TIOCSPGRP  =  $5410  ;
    TIOCOUTQ  =  $5411  ;
    TIOCSTI  =  $5412  ;
    TIOCGWINSZ  =  $5413  ;
    TIOCSWINSZ  =  $5414  ;
    TIOCMGET  =  $5415  ;



                                                                162

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
    TIOCMBIS  =  $5416  ;
    TIOCMBIC  =  $5417  ;
    TIOCMSET  =  $5418  ;
    TIOCGSOFTCAR  =  $5419  ;
    TIOCSSOFTCAR  =  $541A  ;
    FIONREAD  =  $541B  ;
    TIOCINQ  =  FIONREAD;
    TIOCLINUX  =  $541C  ;
    TIOCCONS  =  $541D  ;
    TIOCGSERIAL  =  $541E  ;
    TIOCSSERIAL  =  $541F  ;
    TIOCPKT  =  $5420  ;
    FIONBIO  =  $5421  ;
    TIOCNOTTY  =  $5422  ;
    TIOCSETD  =  $5423  ;
    TIOCGETD  =  $5424  ;
    TCSBRKP  =  $5425    ;
    TIOCTTYGSTRUCT  =  $5426    ;
    FIONCLEX  =  $5450    ;
    FIOCLEX  =  $5451  ;
    FIOASYNC  =  $5452  ;
    TIOCSERCONFIG  =  $5453  ;
    TIOCSERGWILD  =  $5454  ;
    TIOCSERSWILD  =  $5455  ;
    TIOCGLCKTRMIOS  =  $5456  ;
    TIOCSLCKTRMIOS  =  $5457  ;
    TIOCSERGSTRUCT  =  $5458    ;
    TIOCSERGETLSR     =  $5459    ;
    TIOCSERGETMULTI  =  $545A    ;
    TIOCSERSETMULTI  =  $545B    ;
    TIOCMIWAIT  =  $545C  ;
    TIOCGICOUNT  =  $545D  ;
    TIOCPKT_DATA  =  0;
    TIOCPKT_FLUSHREAD  =  1;
    TIOCPKT_FLUSHWRITE  =  2;
    TIOCPKT_STOP  =  4;
    TIOCPKT_START  =  8;
    TIOCPKT_NOSTOP  =  16;
    TIOCPKT_DOSTOP  =  32;


Other than that, all constants for setting the speed and control flags of a terminal line, as
described in the termios (2)  man page, are defined in the linux unit.  It would take too much
place to list them here.  To check the mode field of a stat record, you ca use the following
constants :


   {  Constants  to  check  stat.mode  }
   STAT_IFMT     =  $f000;  {00170000}
   STAT_IFSOCK  =  $c000;  {0140000}
   STAT_IFLNK    =  $a000;  {0120000}
   STAT_IFREG    =  $8000;  {0100000}
   STAT_IFBLK    =  $6000;  {0060000}
   STAT_IFDIR    =  $4000;  {0040000}
   STAT_IFCHR    =  $2000;  {0020000}
   STAT_IFIFO    =  $1000;  {0010000}



                                                                163

___________________________________________11.1.___TYPE,_VARIABLE_AND_CONSTANT_DECLARATIONS________________________________________*
 *___
   STAT_ISUID    =  $0800;  {0004000}
   STAT_ISGID    =  $0400;  {0002000}
   STAT_ISVTX    =  $0200;  {0001000}
   {  Constants  to  check  permissions  }
   STAT_IRWXO  =  $7;
   STAT_IROTH  =  $4;
   STAT_IWOTH  =  $2;
   STAT_IXOTH  =  $1;
   STAT_IRWXG  =  STAT_IRWXO  shl  3;
   STAT_IRGRP  =  STAT_IROTH  shl  3;
   STAT_IWGRP  =  STAT_IWOTH  shl  3;
   STAT_IXGRP  =  STAT_IXOTH  shl  3;
   STAT_IRWXU  =  STAT_IRWXO  shl  6;
   STAT_IRUSR  =  STAT_IROTH  shl  6;
   STAT_IWUSR  =  STAT_IWOTH  shl  6;
   STAT_IXUSR  =  STAT_IXOTH  shl  6;


You  can  test  the  type  of  a  filesystem  returned  by  a  FSStat  (192)  call  with  the  following
constants:


   fs_old_ext2  =  $ef51;
   fs_ext2        =  $ef53;
   fs_ext          =  $137d;
   fs_iso          =  $9660;
   fs_minix       =  $137f;
   fs_minix_30  =  $138f;
   fs_minux_V2  =  $2468;
   fs_msdos       =  $4d44;
   fs_nfs          =  $6969;
   fs_proc        =  $9fa0;
   fs_xia          =  $012FD16D;


the FLock (190) call uses the following mode constants :


   LOCK_SH  =  1;
   LOCK_EX  =  2;
   LOCK_UN  =  8;
   LOCK_NB  =  4;


The MMap (211) function uses the following constants to specify access to mapped memory:


   PROT_READ    =  $1;     {  page  can  be  read  }
   PROT_WRITE  =  $2;     {  page  can  be  written  }
   PROT_EXEC    =  $4;     {  page  can  be  executed  }
   PROT_NONE    =  $0;     {  page  can  not  be  accessed  }


and the following constants to specify the type of mapping.


   MAP_SHARED       =  $1;    {  Share  changes  }
   MAP_PRIVATE     =  $2;    {  Changes  are  private  }
   MAP_TYPE          =  $f;    {  Mask  for  type  of  mapping  }
   MAP_FIXED        =  $10;  {  Interpret  addr  exactly  }
   MAP_ANONYMOUS  =  $20;  {  don't  use  a  file  }
                                                                164

__________________________________________________________________________11.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
11.2          Function  list  by  category


What follows is a listing of the available functions, grouped by category.  For each function
there is a reference to the page where you can find the function.
11.2.1        File  Input/Output  routines

Functions for handling file input/output.


Name_______________________________________________Description_________________________________________________Page___________

  Dup                              Duplicate a file handle                                                       179

  Dup2                             Copy one file handle to another                                          179

  Fcntl                            General file control                                                           195

  fdClose                          Close file descriptor                                                          186

  fdFlush                          Flush file descriptor                                                          187

  fdOpen                           Open new file descriptor                                                    187

  fdRead                           Read from file descriptor                                                   188

  fdSeek                           Position in file                                                                  189

  fdTruncate                       Truncate file                                                                    189

  fdWrite                          Write to file descriptor                                                      190

  GetFS                            Get file descriptor of pascal file                                           199

  Select                           Wait for input from file descriptor                                       220

  SelectText                       Wait for input from pascal file                                            221
11.2.2        General  File  handling  routines

Functions for handling files on disk.


Name_______________________________________________Description_________________________________________________Page___________

  Access                           Check access rights on file                                                  169

  BaseName                         Return name part of file                                                    173

  Chown                            Change owner of file                                                         174

  Chmod                            Change access rights on file                                                175

  DirName                          Return directory part of file                                               178

  FSplit                           Split filename in parts                                                       192

  FExpand                          Return full-grown filename                                                 190

  FLock                            Set lock on a file                                                               190

  FNMatch                          Match filename to searchpattern                                         191

  FSearch                          Search for a file in a path                                                  191

  FSStat                           Return filesystem information                                            192

  FStat                            Return file information                                                      193

  FRename                          Rename file                                                                     195

  LStat                            Return information on a link                                              208



                                                                165

__________________________________________________________________________11.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
  Link                             Create a link                                                                    209

  ReadLink                         Read contents of a symbolic link                                         217

  SymLink                          Create a symbolic link                                                       226

  Umask                            Set the file creation mask                                                   232

  UnLink                           Remove a file                                                                   232

  Utime                            Change file timestamps                                                     233
11.2.3        Pipes,  FIFOs  and  streams

Functions for creating and managing pipes.


Name_______________________________________________Description_________________________________________________Page___________

  AssignPipe                       Create a pipe                                                                   171

  AssignStream                     Create pipes to program's input and output                         171

  MkFifo                           Make a fifo                                                                      211

  PClose                           Close a pipe                                                                     215

  POpen                            Open a pipe for to program's input or output                       216
11.2.4        Directory  handling  routines

Functions for reading and searching directories.


Name_______________________________________________Description_________________________________________________Page___________

  CloseDir                         Close directory handle                                                       177

  Glob                             Return files matching a search expression                             204

  GlobFree                         Free result of Glob                                                            204

  OpenDir                          Open directory for reading                                                 214

  ReadDir                          Read directory entry                                                         217

  SeekDir                          Seek directory                                                                  219

  TellDir                          Seek directory                                                                  231
11.2.5        Process  handling

Functions for managing processes and programs.


Name_______________________________________________Description_________________________________________________Page___________

  Clone                            Create a thread                                                                176

  Execl                            Execute process with command-line list                               181

  Execle                           Execute process with command-line list and environment       181

  Execlp                           Search in path and execute process with command list           182

  Execv                            Execute process                                                                183

  Execve                           Execute process with environment                                      184

  Execvp                           Search in path and execute process                                     185



                                                                166

__________________________________________________________________________11.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
  Fork                             Spawn child process                                                          195

  GetEGid                          Get effective group id                                                        197

  GetEnv                           Get environment variable                                                   198

  GetEUid                          Get effective user id                                                          198

  GetGid                           Get group id                                                                    200

  GetPid                           Get process id                                                                  201

  GetPPid                          Get parent process id                                                        201

  GetPriority                      Get process priority                                                          202

  GetUid                           Get user id                                                                      203

  Nice                             Change priority of process                                                 213

  SetPriority                      Change priority of process                                                 221

  Shell                            Execute shell command                                                     221

  WaitPid                          Wait for child process to terminate                                     233
11.2.6        Signals

Functions for managing and responding to signals.


Name_______________________________________________Description_________________________________________________Page___________

  Alarm                            Send alarm signal to self                                                    170

  Kill                             Send arbitrary signal to process                                          208

  pause                            Wait for signal to arrive                                                    215

  SigAction                        Set signal action                                                               222

  Signal                           Set signal action                                                               225

  SigPending                       See if signals are waiting                                                    223

  SigProcMask                      Set signal processing mask                                                 223

  SigRaise                         Send signal to self                                                             224

  SigSuspend                       Sets signal mask and waits for signal                                   224
11.2.7        System  information

Functions for retrieving system information such as date and time.


Name_______________________________________________Description_________________________________________________Page___________

  GetDate                          Return system date                                                          196

  GetDateTime                      Return system date and time                                             197

  GetDomainName                    Return system domain name                                              197

  GetEpochTime                     Return epoch time                                                            199

  GetHostName                      Return system host name                                                  200

  GetLocalTimezone                 Return system timezone                                                    201

  GetTime                          Return system time                                                          202

  GetTimeOfDay                     Return system time                                                          203



                                                                167

__________________________________________________________________________11.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
  GetTimezoneFile                  Return name of timezone file                                              203

  ReadTimezoneFile                 Read timezone file contents                                                219

  SysInfo                          Return general system information                                      227

  Uname                            Return system information                                                232
11.2.8        Terminal  functions

Functions for controlling the terminal to which the process is connected.


Name_______________________________________________Description_________________________________________________Page___________

  CFMakeRaw                        Set terminal to raw mode                                                  173

  CFSetISpeed                      Set terminal reading speed                                                 174

  CFSetOSpeed                      Set terminal writing speed                                                 174

  IOCtl                            General IO control call                                                      205

  IsATTY                           See if filedescriptor is a terminal                                         206

  TCDrain                          Wait till all output was written                                          228

  TCFlow                           Suspend transmission or receipt of data                               229

  TCFlush                          Discard data written to terminal                                         229

  TCGetAttr                        Get terminal attributes                                                     229

  TCGetPGrp                        Return PID of foreground process                                       230

  TCSendBreak                      Send data for specific time                                                 230

  TCSetAttr                        Set terminal attributes                                                      230

  TCSetPGrp                        Set foreground process                                                      231

  TTYName                          Name of tty file                                                                231
11.2.9        Port  input/output

Functions for reading and writing to the hardware ports.


Name_______________________________________________Description_________________________________________________Page___________

  IOperm                           Set permissions for port access                                           205

  ReadPort                         Read data from port                                                         218

  ReadPortB                        Read 1 byte from port                                                       218

  ReadPortL                        Read 4 bytes from port                                                     218

  ReadPortW                        Read 2 bytes from port                                                     219

  WritePort                        Write data to port                                                            234

  WritePortB                       Write 1 byte to port                                                          234

  WritePortL                       Write 4 bytes to port                                                        235

  WritePortW                       Write 2 bytes to port                                                        235


                                                                168

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.2.10         Utility  routines

                 Auxiliary functions that are useful in connection with the other functions.


                 Name_______________________________________________Description_________________________________________________Pag*
 *e___________

                   CreateShellArgV                  Create an array of pchars from string                                  177

                   EpochToLocal                     Convert epoch time to local time                                        180

                   FD__ Clr                         Clear item of select filedescriptors                                       186

                   FD__ IsSet                       Check item of select filedescriptors                                      186

                   FD__ Set                         Set item of select filedescriptors                                          186

                   FD__ ZERO                        Clear all items in select filedecriptors                                  185

                   LocalToEpoch                     Convert local time to epoch time                                        210

                   MMap                             Map a file into memory                                                     211

                   MUnMap                           Unmap previously mapped memory file                               213

                   Octal                            Convert octal to digital                                                     214

                   S__ ISBLK                        Check file mode for block device                                         206

                   S__ ISCHR                        Check file mode for character device                                    206

                   S__ ISDIR                        Check file mode for directory                                             206

                   S__ ISFIFO                       Check file mode for FIFO                                                  206

                   S__ ISLNK                        Check file mode for symboloc link                                       207

                   S__ ISREG                        Check file mode for regular file                                           207

                   S__ ISSOCK                       Check file mode for socket                                                 207

                   StringToPPchar                   Create an array of pchars from string                                  225
                 11.3          Functions  and  procedures



                 11.3.1        Access

Declaration:      Function  Access  (Path  :    Pathstr;  Mode  :    integer)  :    Boolean;

Description:      Tests user's access rights on the specified file.  Mode is a mask existing of one or more of

                 R___OK    User has read rights.

                 W___OK     User has write rights.

                 X___OK    User has execute rights.

                 F___OK    User has search rights in the directory where the file is.

                 The test is done with the real user ID, instead of the effective user ID. If access is denied, or
                 an error occurred, false is returned.

       Errors:    LinuxError is used to report errors:

                 sys___eaccess     The requested access is denied, either to the file or one of the directories in its
                       path.

                 sys___einval    Mode was incorrect.

                 sys___enoent     A directory component in Path doesn't exist or is a dangling symbolic link.

                 sys___enotdir     A directory component in Path is not a directory.



                                                                                 169

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___enomem        Insufficient kernel memory.

                 sys___eloop    Path has a circular symbolic link.

     See also:    Chown (174), Chmod (175), Access (2)


                 Listing:  linuxex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example26      ;


                 {  Program       to    d e m o n s t r a t et h e A c c e s s  f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    i f   A c c e s s( ' / e t c/ passwd    ' ,W__OK   )  then
                        b e g i n
                        W r i t e l n( ' B e t t e r|_|c h e c|k_|y o u|r_|s y s t e.m') ;
                        W r i t e l n( ' I |_|can |_|w r i t|e_|to|_|t h e|_|/e t/cpasswd     |_|f i l e|_|!)';
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.2        Alarm

Declaration:      Function  Alarm(Sec  :    longint)  :    Longint;

Description:      Alarm schedules an alarm signal to be delivered to your process in Sec seconds.  When Sec
                 seconds have elapsed, Linux will send a SIGALRM signal to the current process.  If Sec is zero,
                 then no new alarm will be set.  Whatever the value of  Sec, any previous alarm is cancelled.

                 The function returns the number of seconds till the previously scheduled alarm was due to
                 be delivered, or zero if there was none.

       Errors:    None


                 Listing:  linuxex/ex59.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example59      ;


                 {  Program       to    d e m o n s t r a t et h e Alarm      f u n c t i o n.  }


                 Uses     l i n u x;


                 Procedure        A l a r m H a n d l e(rS i g  :   l o n g i n t) ;c d e c l;


                 b e g i n
                    W r i t e l n ( ' Got  |_|to|_|a l a r m|_|h a n d l e'r) ;
                 end  ;


                 b e g i n
                    W r i t e l n(' S e t t i n g|_|a l a r|m_|h a n d l e'r) ;
                    S i g n a l(SIGALRM      ,@ A l a r m H a n d l e)r;
                    W r i t e l n ( ' S c h e d u l i n|g_|Alarm  |_|i n|_|10 |_|s e c o n'd)s;
                    Alarm    ( 1 0 ) ;
                    W r i t e l n ( ' P a u s i n g') ;
                    Pause    ;
                    W r i t e l n ( ' Pause   |_|r e t u r n e'd) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 170

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.3        AssignPipe

Declaration:      Function  AssignPipe(var  pipe__ in,pipe__ out:longint):boolean;  Function  AssignPipe(var
                 pipe__ in,pipe__ out:text):boolean;  Function  AssignPipe(var  pipe__ in,pipe__ out:file):boolean;

Description:      AssignePipe creates a pipe, i.e.  two file objects, one for input, one for output.  What is
                 written to Pipe__ out, can be read from Pipe__ in.

                 This call is overloaded.  The in and out pipe can take three forms:  an typed or untyped file,
                 a text file or a file descriptor.

                 If a text file is passed then reading and writing from/to the pipe can be done through the
                 usual Readln(Pipe__ in,...)  and Writeln  (Pipe__ out,...)  procedures.

                 The function returns True if everything went succesfully, False otherwise.

       Errors:    In case the function fails and returns False, LinuxError is used to report errors:

                 sys___emfile    Too many file descriptors for this process.

                 sys___enfile   The system file table is full.

     See also:    POpen (216), MkFifo (211), pipe (2)


                 Listing:  linuxex/ex36.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example36      ;


                 {  Program       to    d e m o n s t r a t et h e A s s i g n P i p e f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    p i p i, p i p o :   Text   ;
                        s  :   S t r i n g;


                 b e g i n
                    W r i t e l n ( ' A s s i g n i n|g_|P i p e.s') ;
                    I f  Not     a s s i g n p i p(ep i p i,p i p o)   then
                        W r i t e l n(' E r r o r|_|a s s i g n i n|g_|p i p|e_s|!,'L i n u x E r r o)r;
                    W r i t e l n ( ' W r i t i n g|_|to|_|p i p,e|_|and |_|f l u s h i n.g') ;
                    W r i t e l n ( p i p o, 'T h i s|_|i s|_|a|_|t e x t s t r i'n)g; c l o s e(p i p o) ;
                    W r i t e l n ( ' R e a d i n g|_|from |_|p i p e. ') ;
                    While      not    e o f( p i p i)  do
                        b e g i n
                        Readln      ( p i p i,s ) ;
                        W r i t e l n( ' Read   |_|from  |_|p i p e|_|: |_|',s) ;
                        end  ;
                    c l o s e (  p i p i) ;
                    w r i t e l n ( ' C l o s e d|_|p i p e.s') ;
                    w r i t e l n
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.4        AssignStream

Declaration:      Function  AssignStream(Var  StreamIn,Streamout:text;  Const  Prog:String)  :    longint;
                 Function  AssignStream(var  StreamIn,  StreamOut,  StreamErr:    Text;  const  prog:    String):
                 LongInt;

Description:      AssignStream creates a 2 or 3 pipes, i.e.  two (or three) file objects, one for input, one for
                 output,(and one for standard error) the other ends of these pipes are connected to standard



                                                                                 171

            __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES_____________*
 *_______________
            input and output (and standard error) of  Prog.  Prog is the name of a program (including
            path) with options, which will be executed.

            What is written to StreamOut, will go to the standard input of  Prog.  Whatever is written
            by Prog to it's standard output can be read from StreamIn.  Whatever is written by Prog
            to it's standard error read from StreamErr, if present.

            Reading  and  writing  happens  through  the  usual  Readln(StreamIn,...)   and  Writeln
            (StreamOut,...)  procedures.

            Remark:  You should not use Reset or Rewrite on a file opened with POpen.  This will close
            the file before re-opening it again, thereby closing the connection with the program.

            The function returns the process ID of the spawned process, or -1 in case of error.

  Errors:    In case of error (return value -1) LinuxError is used to report errors:

            sys___emfile    Too many file descriptors for this process.

            sys___enfile   The system file table is full.

            Other errors include the ones by the fork and exec programs

See also:    AssignPipe (171), POpen (216),pipe (2)


            Listing:  linuxex/ex38.pp

           ________________________________________________________________________________________________________________________*
 *________
            Program       Example38      ;


            {  Program       to    d e m o n s t r a t et h e A s s i g n S t r e a mf u n c t i o n.  }


            Uses     l i n u x;


            Var    S i, So   :   Text   ;
                   S  :   S t r i n g;
                   i  :   l o n g i n t;


            b e g i n
               i f  not    ( p a r a m s t r(1)=  '-  son  ' )  then
                   b e g i n
                   W r i t e l n( ' C a l l i n g|_|son' ) ;
                   A s s i g n s t r e a m(S i ,So  , ' . /ex38   |_|-son  ') ;
                   i f  l i n u x e r r o<r>0   then
                      b e g i n
                      w r i t e l n ( ' A s s i g n S t r e a|m_|f a i l e|d_|!)';
                      h a l t( 1 ) ;
                      end   ;
                   W r i t e l n( ' S p e a k i n g|_|to|_|son' ) ;
                   For    i:=1    to   1 0   do
                      b e g i n
                      w r i t e l n ( so , ' H e l l o|_|son |_|! ') ;
                      i f   i o r e s u l<t>0   then     w r i t e l n ( 'Can   ' 't |_|s p e a k|_|to|_|son. . . ') ;
                      end   ;
                   For    i:=1    to   3   do    w r i t e l n( so  ,' H e l l o|_|chap  |_|! ') ;
                   c l o s e ( so  ) ;
                   w h i l e not    e o f( s i )  do
                      b e g i n
                      r e a d l n ( s i ,s ) ;
                      w r i t e l n ( ' F a t h e r: |_|Son|_|s a i d|_|: |_|',S) ;
                      end   ;
                   W r i t e l n( ' S t o p p e d|_|c o n v e r s a t i'o)n;



                                                                            172

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                        C l o s e ( S i ) ;
                        W r i t e l n( ' Put  |_|down  |_|phone   ') ;
                        end
                    E l s e
                        b e g i n
                        W r i t e l n( ' T h i s|_|i s|_|t h|e_|son |_|') ;
                        While     not    e o f  ( i n p u t)  do
                           b e g i n
                           r e a d l n ( s ) ;
                           i f  pos    ( ' H e l l o|_|son |_|! ',S)<>0     then
                                 W r i t e l n( ' H e l l o|_|Dad |_|! ')
                           e l s e
                                 w r i t e l n( ' Who  |_|a r e|_|you|_|? ') ;
                           end   ;
                        c l o s e ( o u t p u t) ;
                        end
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.5        BaseName

Declaration:      Function  BaseName  (Const  Path;Const  Suf  :    Pathstr)  :    Pathstr;

Description:      Returns the filename part of  Path, stripping off  Suf if it exists.  The filename part is the
                 whole  name  if  Path  contains  no  slash,  or  the  part  of  Path  after  the  last  slash.   The  last
                 character of the result is not a slash, unless the directory is the root directory.

       Errors:    None.

     See also:    DirName (178), FExpand (190), Basename (1)


                 Listing:  linuxex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example48      ;


                 {  Program       to    d e m o n s t r a t et h e BaseName        f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    S  :   S t r i n g;


                 b e g i n
                    S := FExpand      (Paramstr       ( 0 ) ) ;
                    W r i t e l n ( ' T h i s|_|program    |_|i s|_|c a l l e|d_|: |_|',Basename   (S , ' ' ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.6        CFMakeRaw

Declaration:      Procedure  CFMakeRaw  (var  Tios:TermIOS);

Description:      CFMakeRaw Sets the flags in the Termios structure Tios to a state so that the terminal will
                 function in Raw Mode.

       Errors:    None.

     See also:    CFSetOSpeed (174), CFSetISpeed (174), termios (2)


                 For an example, see TCGetAttr (229).



                                                                                 173

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.7        CFSetISpeed

Declaration:      Procedure  CFSetISpeed  (var  Tios:TermIOS;Speed:Longint);

Description:      CFSetISpeed Sets the input baudrate in the TermIOS structure Tios to Speed.

       Errors:    None.

     See also:    CFSetOSpeed (174), CFMakeRaw (173), termios (2)
                 11.3.8        CFSetOSpeed

Declaration:      Procedure  CFSetOSpeed  (var  Tios:TermIOS;Speed:Longint);

Description:      CFSetOSpeed Sets the output baudrate in the Termios structure Tios to Speed.

       Errors:    None.

     See also:    CFSetISpeed (174), CFMakeRaw (173), termios (2)
                 11.3.9        Chown

Declaration:      Function  Chown  (Path  :    Pathstr;NewUid,NewGid  :    Longint)  :    Boolean;

Description:      Chown sets the User ID and Group ID of the file in Path to NewUid,  NewGid.  The function
                 returns True if the call was succesfull, False if the call failed.

       Errors:    Errors are returned in LinuxError.

                 sys___eperm      The  effective  UID  doesn't  match  the  ownership  of  the  file,  and  is  not  zero.
                       Owner or group were not specified correctly.

                 sys___eaccess     One of the directories in Path has no search (=execute) permission.

                 sys___enoent     A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                       non-existent directory.

                 sys___enotdir     A directory entry in OldPath or NewPath is nor a directory.

                 sys___enomem        Insufficient kernel memory.

                 sys___erofs   The file is on a read-only filesystem.

                 sys___eloop    Path  has  a  reference  to  a  circular  symbolic  link,  i.e.   a  symbolic  link,  whose
                       expansion points to itself.

     See also:    Chmod (175), Access (169), Chown (() 2)


                 Listing:  linuxex/ex24.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example24      ;


                 {  Program       to    d e m o n s t r a t et h e Chown      f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    UID  , GID    :  L o n g i n t;
                        F  :   Text   ;


                 b e g i n


                    W r i t e l n ( ' T h i s|_|w i l|l_|o n l|y_|work |_|i f|_|you|_|a r e|_|r o o.t') ;



                                                                                 174

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    Write     (  'E n t e r|_|a|_|UID |_|: |_|')r;e a d l n(UID  ) ;
                    Write     (  'E n t e r|_|a|_|GID |_|: |_|')r;e a d l n(GID  ) ;
                    A s s i g n ( f , ' t e s t.t x t' ) ;
                    R e w r i t e ( f ) ;
                    W r i t e l n ( f ,' The  |_|owner   |_|o f|_|t h i|s_|f i l|e_|s h o u l|d_|become |_|: |_|') ;
                    W r i t e l n ( f ,' UID   |_|: |_|',UID) ;
                    W r i t e l n ( f ,' GID   |_|: |_|',GID) ;
                    C l o s e ( F ) ;
                    i f  not    Chown      ( ' t e s t.t x t' , UID  , GID  )  then
                        i f  L i n u x E r r o=rSys__EPERM        then
                           W r i t e l n ( 'You   |_|a r e|_|not|_|r o o t|_|!)'
                        e l s e
                           W r i t e l n ( 'Chmod    |_|f a i l e d|_|w i t|h_|e x i|t_|code|_|: |_|',L i n u x E r r o)r
                    e l s e
                        W r i t e l n( ' Changed     |_|owner   |_|s u c c e s s f u l l|y_|!)';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.10         Chmod

Declaration:      Function  Chmod  (Path  :    Pathstr;NewMode  :    Longint)  :    Boolean;

Description:      Chmod  Sets  the  Mode  bits  of  the  file  in  Path  to  NewMode.  Newmode  can  be  specified  by
                 'or'-ing the following:

                 S___ISUID     Set user ID on execution.

                 S___ISGID     Set Group ID on execution.

                 S___ISVTX      Set sticky bit.

                 S___IRUSR       Read by owner.

                 S___IWUSR        Write by owner.

                 S___IXUSR       Execute by owner.

                 S___IRGRP       Read by group.

                 S___IWGRP        Write by group.

                 S___IXGRP       Execute by group.

                 S___IROTH       Read by others.

                 S___IWOTH        Write by others.

                 S___IXOTH       Execute by others.

                 S___IRWXO        Read, write, execute by others.

                 S___IRWXG        Read, write, execute by groups.

                 S___IRWXU        Read, write, execute by user.

       Errors:    Errors are returned in LinuxError.

                 sys___eperm      The  effective  UID  doesn't  match  the  ownership  of  the  file,  and  is  not  zero.
                       Owner or group were not specified correctly.

                 sys___eaccess     One of the directories in Path has no search (=execute) permission.

                 sys___enoent     A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                       non-existent directory.

                 sys___enotdir     A directory entry in OldPath or NewPath is nor a directory.

                 sys___enomem        Insufficient kernel memory.

                 sys___erofs   The file is on a read-only filesystem.



                                                                                 175

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___eloop    Path  has  a  reference  to  a  circular  symbolic  link,  i.e.   a  symbolic  link,  whose
                       expansion points to itself.

     See also:    Chown (174), Access (169), Chmod (() 2), Octal (214)


                 Listing:  linuxex/ex23.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example23      ;


                 {  Program       to    d e m o n s t r a t et h e Chmod      f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    F  :   Text   ;


                 b e g i n
                    {   C r e a t e a   f i l e }
                    A s s i g n ( f , ' t e s t e x 2'1) ;
                    R e w r i t e ( F ) ;
                    W r i t e l n ( f ,'#!/   b i n/ sh  ' ) ;
                    W r i t e l n ( f ,' echo   |_|Some  |_|t e x t|_|f o|r_|t h i|s_|f i l'e) ;
                    C l o s e ( F ) ;
                    {   O c t a l( )  makes     t h e  c o r r e c t number      from     a
                        number      t h a t LOOKS      o c t a l }
                    Chmod     (  't e s t e x 2 1', o c t a l ( 7 7 7 ) ) ;
                    {   F i l e  i s  now    e x e c u t a b l e }
                    e x e c l (  ' . /t e s t e x 2 1') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.11         Clone

Declaration:      TCloneFunc=function(args:pointer):longint;cdecl;  Clone(func:TCloneFunc;sp:pointer;flags:longint;args:pointer):lo*
 *ngint;

Description:      Clone  creates  a  child  process  which  is  a  copy  of  the  parent  process,  just  like  Fork  (195)
                 does.  In difference with Fork, however, the child process shares some parts of it's execution
                 context with its parent, so it is suitable for the implementation of threads:  many instances
                 of a program that share the same memory.

                 When the child process is created, it starts executing the function Func, and passes it Args.
                 The return value of  Func is either the explicit return value of the function, or the exit code
                 of the child process.

                 The  sp  pointer  points  to  the  memory  reserved  as  stack  space  for  the  child  process.  This
                 address should be the top of the memory block to be used as stack.

                 The Flags determine the behaviour of the Clone call.  The low byte of the Flags contains
                 the number of the signal that will be sent to the parent when the child dies.  This may be
                 bitwise OR'ed with the following constants:

                 CLONE___VM           Parent and child share the same memory space, including memory (un)mapped
                       with subsequent mmap calls.

                 CLONE___FS         Parent and child have the same view of the filesystem; the chroot, chdir and
                       umask calls affect both processes.

                 CLONE___FILES            the file descriptor table of parent and child is shared.

                 CLONE___SIGHAND                 the  parent  and  child  share  the  same  table  of  signal  handlers.  The
                       signal masks are different, though.
                                                                                 176

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 CLONE___PID          PArent and child have the same process ID.

                 Clone returns the process ID in the parent process, and -1 if an error occurred.

       Errors:    On error, -1 is returned to the parent, and no child is created.

                 sys___eagain     Too many processes are running.

                 sys___enomem        Not enough memory to create child process.

     See also:    Fork (195), clone (2)


                 Listing:  linuxex/ex14.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example14      ;


                 {  Program       to    d e m o n s t r a t et h e Fork     and    W a i t P i d f u n c t i o.n }


                 Uses     l i n u x;


                 Var    PID  ,   E x i t S t a t u s:  L o n g i n t;


                 b e g i n
                    W r i t e l n ( ' Spawning      |_|a|_|c h i l'd) ;
                    PID  :=  Fork   ;
                    I f  PID   =0   then
                        b e g i n
                        W r i t e l n( ' H e l l o|_|From  |_|t h e|_|C h i l|d_|! !)';
                        W r i t e l n( ' E x i t i n g|_|w i t|h_|e x i|t_|s t a t u|s_|1 |_|!)';
                        Halt    ( 1 ) ;
                        end
                    E l s e
                        b e g i n
                        W r i t e l n( ' Spawned     |_|c h i l d|_|w i t|h_|PID|_|: |_|',PID ) ;
                        W a i t P i d( PID   , @ E x i t S t a t u,s0 ) ;
                        W r i t e l n( ' C h i l d|_|e x i t e|d_|w i t|h_|s t a t u|s_|: |_|',E x i t S t a t ussh r 8 ) ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.12         CloseDir

Declaration:      Function  CloseDir  (p:pdir)  :    integer;

Description:      CloseDir closes the directory pointed to by p.  It returns zero if the directory was closed
                 succesfully, -1 otherwise.

       Errors:    Errors are returned in LinuxError.

     See also:    OpenDir (214), ReadDir (217), SeekDir (219), TellDir (231), closedir (3)


                 For an example, see OpenDir (214).
                 11.3.13         CreateShellArgV

Declaration:      function  CreateShellArgV(const  prog:string):ppchar;  function  CreateShellArgV(const
                 prog:Ansistring):ppchar;

                                                                                 177

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      CreateShellArgV creates an array of 3 PChar pointers that can be used as arguments to
                 ExecVE the first elements in the array will contain /bin/sh, the second will contain -c, and
                 the third will contain prog.

                 The function returns a pointer to this array, of type PPChar.

       Errors:    None.

     See also:    Shell (221)


                 Listing:  linuxex/ex61.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex61   ;


                 {  Example       program       to   d e m o n s t r a t et h e  C r e a t e S h e l l A r g Vf u n c t i o n}


                 u s e s  l i n u x;


                 Var
                    S :   S t r i n g;
                    PP   :   PPchar    ;
                      I  :   l o n g i n t;


                 b e g i n
                    S :=  's c r i p t|_|-a|_|-b|_|-c|_|-d |_|-e|_|f g h i j'k;
                    PP  := C r e a t e S h e l l A r g(VS) ;
                    I : = 0 ;
                    I f  PP <>   N i l then
                        While     PP  [ i]<>  N i l  do
                           b e g i n
                           W r i t e l n ( ' Got  |_|: |_|",'PP [ i ] ,' " ') ;
                           I n c( i ) ;
                           end   ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.14         DirName

Declaration:      Function  DirName  (Const  Path  :    Pathstr)  :    Pathstr;

Description:      Returns the directory part of Path.  The directory is the part of Path before the last slash,
                 or  empty  if  there  is  no  slash.   The  last  character  of  the  result  is  not  a  slash,  unless  the
                 directory is the root directory.

       Errors:    None.

     See also:    BaseName (173), FExpand (190), Dirname (1)


                 Listing:  linuxex/ex47.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example47      ;


                 {  Program       to    d e m o n s t r a t et h e DirName       f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    S  :   S t r i n g;

                                                                                 178

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 b e g i n
                    S := FExpand      (Paramstr       ( 0 ) ) ;
                    W r i t e l n ( ' T h i s|_|program    |_|i s|_|i|n_|d i r e c t o r|y_|: |_|',Dirname ( S ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.15         Dup

Declaration:      Function  Dup(oldfile:longint;var  newfile:longint):Boolean;  Function  Dup(var  oldfile,newfile:text):Boolean;
                 Function  Dup(var  oldfile,newfile:file):Boolean;

Description:      Makes  NewFile  an  exact  copy  of  OldFile,  after  having  flushed  the  buffer  of  OldFile  in
                 case it is a Text file or untyped file.  Due to the buffering mechanism of Pascal, this has not
                 the same functionality as the dup (2)  call in C. The internal Pascal buffers are not the same
                 after  this  call,  but  when  the  buffers  are  flushed  (e.g.  after  output),  the  output  is  sent  to
                 the same file.  Doing an lseek will, however, work as in C, i.e.  doing a lseek will change the
                 fileposition in both files.

                 The function returns False in case of an error, True if successful.

       Errors:    In case of errors, Linuxerror is used to report errors.

                 sys___ebadf    OldFile hasn't been assigned.

                 sys___emfile    Maximum number of open files for the process is reached.

     See also:    Dup2 (179), Dup (2)


                 Listing:  linuxex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 program       Example31      ;


                 {  Program       to    d e m o n s t r a t et h e Dup    f u n c t i o n.  }


                 u s e s  l i n u x;


                 v a r  f  :   t e x t;


                 b e g i n
                    i f  not    dup    ( o u t p u t,f )   then
                        W r i t e l n( ' Dup  |_|F a i l e d|_|!)';
                    w r i t e l n ( ' T h i s|_|i s|_|w r i t t e|n_|to|_|s t d o.u't) ;
                    w r i t e l n ( f ,' T h i s|_|i s|_|w r i t t e|n_|to|_|t h|e_|dup|_|f i l,e|_|and |_|f l u s h e'd) ;f l u s *
 *h( f) ;
                    w r i t e l n
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.16         Dup2

Declaration:      Function  Dup2(oldfile,newfile:longint):Boolean;  Function  Dup2(var  oldfile,newfile:text):Boolean;
                 Function  Dup2(var  oldfile,newfile:file):Boolean;

Description:      Makes  NewFile  an  exact  copy  of  OldFile,  after  having  flushed  the  buffer  of  OldFile  in
                 the case of text or untyped files.

                 NewFile can be an assigned file.  If newfile was open, it is closed first.  Due to the buffering
                 mechanism  of  Pascal,  this  has  not  the  same  functionality  as  the  dup2  (2)   call  in  C.  The
                 internal Pascal buffers are not the same after this call, but when the buffers are flushed (e.g.
                 after output), the output is sent to the same file.  Doing an lseek will, however, work as in
                 C, i.e.  doing a lseek will change the fileposition in both files.



                                                                                 179

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 The function returns True if succesful, false otherwise.

       Errors:    In case of error, Linuxerror is used to report errors.

                 sys___ebadf    OldFile hasn't been assigned.

                 sys___emfile    Maximum number of open files for the process is reached.

     See also:    Dup (179), Dup2 (2)


                 Listing:  linuxex/ex32.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       Example31      ;


                 {  Program       to    d e m o n s t r a t et h e Dup    f u n c t i o n.  }


                 u s e s  l i n u x;


                 v a r  f  :   t e x t;
                        i  :   l o n g i n t;


                 b e g i n
                    A s s i g n ( f , ' t e x t.t x t' ) ;
                    R e w r i t e ( F ) ;
                    For    i :=1    to   1 0  do    w r i t e l n( F , ' L i n e|_|: |_|',i) ;
                    i f  not    dup2     ( o u t p u t,f )  then
                        W r i t e l n( ' Dup2   |_|F a i l e d|_|!)';
                    w r i t e l n ( ' T h i s|_|i s|_|w r i t t e|n_|to|_|s t d o.u't) ;
                    w r i t e l n ( f ,' T h i s|_|i s|_|w r i t t e|n_|to|_|t h|e_|dup|_|f i l,e|_|and |_|f l u s h e'd) ;
                    f l u s h( f ) ;
                    w r i t e l n;
                    {   Remove      f i l e.  Comment        t h i s i f  you    want     to   c h e c k  f l u s h i n g. }
                    U n l i n k ( ' t e x t. t x t' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.17         EpochToLocal

Declaration:      Procedure  EpochToLocal  (Epoch  :    Longint;  var  Year,Month,Day,Hour,Minute,Second
                 :    Word);

Description:      Converts the epoch time (=Number of seconds since 00:00:00 , January 1, 1970, corrected
                 for your time zone ) to local date and time.

                 This function takes into account the timzeone settings of your system.

       Errors:    None

     See also:    GetEpochTime (199), LocalToEpoch (210), GetTime (202),GetDate (196)


                 Listing:  linuxex/ex3.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example3      ;


                 {  Program       to    d e m o n s t r a t et h e E p o c h T o L o c a lf u n c t i o n.  }


                 Uses     l i n u x;


                 Var    Year   ,month    , day  , h o u r, m i n u t e,s e c o n d s :  Word   ;



                                                                                 180

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________


                 b e g i n
                    E p o c h T o L o c a l( GetEpochTime         ,Year   , month    ,day   ,h o u r, m i n u t e,s e c o n d s) ;
                    W r i t e l n ( ' C u r r e n t|_|d a t|e_|: |_|',Day: 2 ,' / ', Month    : 2 ,' / ', Year   : 4 ) ;
                    W r i t e l n ( ' C u r r e n t|_|t i m|e_|: |_|',Hour: 2 , ' : ', m i n u t e: 2 ,' : ',s e c o n d s: 2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.18         Execl

Declaration:      Procedure  Execl  (Path  :    pathstr);

Description:      Replaces the currently running program with the program, specified in path.  Path is split
                 into a command and it's options.  The executable in path is NOT searched in the path.  The
                 current environment is passed to the program.  On success, execl does not return.

       Errors:    Errors are reported in LinuxError:

                 sys___eacces     File is not a regular file, or has no execute permission.  A compononent of the
                       path has no search permission.

                 sys___eperm      The file system is mounted noexec.

                 sys___e2big    Argument list too big.

                 sys___enoexec      The magic number in the file is incorrect.

                 sys___enoent     The file does not exist.

                 sys___enomem        Not enough memory for kernel, or to split command line.

                 sys___enotdir     A component of the path is not a directory.

                 sys___eloop    The path contains a circular reference (via symlinks).

     See also:    Execve (184), Execv (183), Execvp (185), Execle (181), Execlp (182), Fork (195), execvp (3)


                 Listing:  linuxex/ex10.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;


                 {  Program       to    d e m o n s t r a t et h e E x e c l  f u n c t i o n.  }


                 Uses     l i n u x,  s t r i n g s;


                 b e g i n
                    {   E x e c u t e ' l s -  l' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   ' l s'   i s NOT     l o o k e d f o r  i n  PATH     e n v i r o n m e n tv a r i a b l e. }
                    E x e c l (  ' /b i n/ l s|_|-l ' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.19         Execle

Declaration:      Procedure  Execle  (Path  :    pathstr,  Ep  :    ppchar);

Description:      Replaces the currently running program with the program, specified in path.  Path is split
                 into a command and it's options.  The executable in path is searched in the path, if it isn't
                 an absolute filename.  The environment in ep is passed to the program.  On success, execle
                 does not return.

       Errors:    Errors are reported in LinuxError:



                                                                                 181

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___eacces     File is not a regular file, or has no execute permission.  A compononent of the
                       path has no search permission.

                 sys___eperm      The file system is mounted noexec.

                 sys___e2big    Argument list too big.

                 sys___enoexec      The magic number in the file is incorrect.

                 sys___enoent     The file does not exist.

                 sys___enomem        Not enough memory for kernel, or to split command line.

                 sys___enotdir     A component of the path is not a directory.

                 sys___eloop    The path contains a circular reference (via symlinks).

     See also:    Execve (184), Execv (183), Execvp (185), Execl (181), Execlp (182), Fork (195), execvp (3)


                 Listing:  linuxex/ex11.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example11      ;


                 {  Program       to    d e m o n s t r a t et h e E x e c l e  f u n c t i o n.  }


                 Uses     l i n u x,  s t r i n g s;


                 b e g i n
                    {   E x e c u t e ' l s -  l' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   ' l s'   i s NOT     l o o k e d f o r  i n  PATH     e n v i r o n m e n tv a r i a b l e. }
                    {   envp     i s  d e f i n e d i n  t h e  s y s t e m u n i t. }
                    E x e c l e ( ' / b i n/ l s|_|-l' , envp   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.20         Execlp

Declaration:      Procedure  Execlp  (Path  :    pathstr);

Description:      Replaces the currently running program with the program, specified in path.  Path is split
                 into a command and it's options.  The executable in path is searched in the path, if it isn't an
                 absolute filename.  The current environment is passed to the program.  On success, execlp
                 does not return.

       Errors:    Errors are reported in LinuxError:

                 sys___eacces     File is not a regular file, or has no execute permission.  A compononent of the
                       path has no search permission.

                 sys___eperm      The file system is mounted noexec.

                 sys___e2big    Argument list too big.

                 sys___enoexec      The magic number in the file is incorrect.

                 sys___enoent     The file does not exist.

                 sys___enomem        Not enough memory for kernel, or to split command line.

                 sys___enotdir     A component of the path is not a directory.

                 sys___eloop    The path contains a circular reference (via symlinks).

     See also:    Execve (184), Execv (183), Execvp (185), Execle (181), Execl (181), Fork (195), execvp (3)


                 Listing:  linuxex/ex12.pp



                                                                                 182

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example12      ;


                 {  Program       to    d e m o n s t r a t et h e E x e c l p  f u n c t i o n.  }


                 Uses     l i n u x,  s t r i n g s;


                 b e g i n
                    {   E x e c u t e ' l s -  l' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   ' l s'   i s  l o o k e d f o r  i n  PATH     e n v i r o n m e n tv a r i a b l e. }
                    {   envp     i s  d e f i n e d i n  t h e  s y s t e m u n i t. }
                    E x e c l p ( ' l s|_|-l ', envp   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.21         Execv

Declaration:      Procedure  Execv  (Path  :    pathstr;  args  :    ppchar);

Description:      Replaces the currently running program with the program, specified in path.  It gives the
                 program the options in args.  This is a pointer to an array of pointers to null-terminated
                 strings.  The last pointer in this array should be nil.  The current environment is passed to
                 the program.  On success, execv does not return.

       Errors:    Errors are reported in LinuxError:

                 sys___eacces     File is not a regular file, or has no execute permission.  A compononent of the
                       path has no search permission.

                 sys___eperm      The file system is mounted noexec.

                 sys___e2big    Argument list too big.

                 sys___enoexec      The magic number in the file is incorrect.

                 sys___enoent     The file does not exist.

                 sys___enomem        Not enough memory for kernel.

                 sys___enotdir     A component of the path is not a directory.

                 sys___eloop    The path contains a circular reference (via symlinks).

     See also:    Execve (184), Execvp (185), Execle (181), Execl (181), Execlp (182), Fork (195), execv (3)


                 Listing:  linuxex/ex8.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;


                 {  Program       to    d e m o n s t r a t et h e Execv      f u n c t i o n.  }


                 Uses     l i n u x,  s t r i n g s;


                 Const     Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  Pchar     =   '-  l ';


                 Var   PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(Pchar    ) ) ;
                    PP  [ 0 ] : =Arg0  ;



                                                                                 183

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 3 ] : =N i l;
                    {   E x e c u t e ' /b i n/ l s -  l ' ,  w i t h  c u r r e n t e n v i r o n m e n t}
                    Execv     (  ' /b i n/ l s' , pp  ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.22         Execve

Declaration:      Procedure  Execve(Path:pchar;args:ppchar;ep:ppchar);  Procedure  Execve  (Path  :
                 pathstr;  args,ep  :    ppchar);

Description:      Replaces the currently running program with the program, specified in path.  It gives the
                 program the options in args, and the environment in ep.  They are pointers to an array of
                 pointers to null-terminated strings.  The last pointer in this array should be nil.  On success,
                 execve does not return.

       Errors:    Errors are reported in LinuxError:

                 eacces   File is not a regular file, or has no execute permission.  A compononent of the path
                       has no search permission.

                 sys___eperm      The file system is mounted noexec.

                 sys___e2big    Argument list too big.

                 sys___enoexec      The magic number in the file is incorrect.

                 sys___enoent     The file does not exist.

                 sys___enomem        Not enough memory for kernel.

                 sys___enotdir     A component of the path is not a directory.

                 sys___eloop    The path contains a circular reference (via symlinks).

     See also:    Execve (184), Execv (183), Execvp (185) Execle (181), Execl (181), Execlp (182), Fork (195),
                 execve (2)


                 Listing:  linuxex/ex7.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example7      ;


                 {  Program       to    d e m o n s t r a t et h e E x e c v e  f u n c t i o n.  }


                 Uses     l i n u x,  s t r i n g s;


                 Const     Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  Pchar     =   '-  l ';


                 Var   PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(Pchar    ) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 3 ] : =N i l;
                    {   E x e c u t e ' /b i n/ l s -  l ' ,  w i t h  c u r r e n t e n v i r o n m e n t}
                    {   Envp     i s  d e f i n e d i n  s y s t e m.i n c  }
                    ExecVe      ( ' / b i n/ l s' , pp , envp   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 184

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.23         Execvp

Declaration:      Procedure  Execvp  (Path  :    pathstr;  args  :    ppchar);

Description:      Replaces  the  currently  running  program  with  the  program,  specified  in  path.   The  exe-
                 cutable in path is searched in the path, if it isn't an absolute filename.  It gives the program
                 the options in args.  This is a pointer to an array of pointers to null-terminated strings.  The
                 last pointer in this array should be nil.  The current environment is passed to the program.
                 On success, execvp does not return.

       Errors:    Errors are reported in LinuxError:

                 sys___eacces     File is not a regular file, or has no execute permission.  A compononent of the
                       path has no search permission.

                 sys___eperm      The file system is mounted noexec.

                 sys___e2big    Argument list too big.

                 sys___enoexec      The magic number in the file is incorrect.

                 sys___enoent     The file does not exist.

                 sys___enomem        Not enough memory for kernel.

                 sys___enotdir     A component of the path is not a directory.

                 sys___eloop    The path contains a circular reference (via symlinks).

     See also:    Execve (184), Execv (183), Execle (181), Execl (181), Execlp (182), Fork (195), execvp (3)


                 Listing:  linuxex/ex9.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example9      ;


                 {  Program       to    d e m o n s t r a t et h e Execvp       f u n c t i o n.  }


                 Uses     l i n u x,  s t r i n g s;


                 Const     Arg0     :  PChar     =   ' l s ';
                           Arg1     :  Pchar     =   '-  l ';


                 Var   PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(Pchar    ) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 3 ] : =N i l;
                    {   E x e c u t e ' l s -  l' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   ' l s'   i s  l o o k e d f o r  i n  PATH     e n v i r o n m e n tv a r i a b l e. }
                    {   Envp     i s  d e f i n e d i n  t h e  s y s t e m u n i t.  }
                    Execvp      ( ' l s' , pp , envp   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.24         FD___ZERO

Declaration:      Procedure  FD__ ZERO  (var  fds:fdSet);

Description:      FD__ ZERO clears all the filedescriptors in the file descriptor set fds.
                                                                                 185

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    None.

     See also:    Select (220), SelectText (221), GetFS (199), FD__ Clr (186), FD__ Set (186), FD__ IsSet (186)


                 For an example, see Select (220).
                 11.3.25         FD___Clr

Declaration:      Procedure  FD__ Clr  (fd:longint;var  fds:fdSet);

Description:      FD__ Clr clears file descriptor fd in filedescriptor s et fds.

       Errors:    None.

     See also:    Select (220), SelectText (221), GetFS (199), FD__ ZERO (185), FD__ Set (186), FD__ IsSet (186)


                 For an example, see Select (220).
                 11.3.26         FD___IsSet

Declaration:      Function  FD__ IsSet  (fd:longint;var  fds:fdSet)  :    boolean;

Description:      FD__ Set Checks whether file descriptor fd in filedescriptor set fds is set.

       Errors:    None.

     See also:    Select (220), SelectText (221), GetFS (199), FD__ ZERO (185), FD__ Clr (186), FD__ Set (186)


                 For an example, see Select (220).
                 11.3.27         FD___Set

Declaration:      Procedure  FD__ Set  (fd:longint;var  fds:fdSet);

Description:      FD__ Set sets file descriptor fd in filedescriptor set fds.

       Errors:    None.

     See also:    Select (220), SelectText (221), GetFS (199),FD__ ZERO (185), FD__ Clr (186), FD__ IsSet (186)


                 For an example, see Select (220).
                 11.3.28         fdClose

Declaration:      Function  fdClose  (fd:longint)  :    boolean;

Description:      fdClose closes a file with file descriptor Fd.  The function returns True if the file was closed
                 successfully, False otherwise.

       Errors:    Errors are returned in LinuxError

     See also:    fdOpen (187), fdRead (188), fdWrite (190),fdTruncate (189), fdFlush (187), seefFdSeek


                 For an example, see fdOpen (187).


                                                                                 186

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.29         fdFlush

Declaration:      Function  fdFlush  (fd:Longint)  :    boolean;

Description:      fdflush flushes the Linux kernel file buffer, so the file is actually written to disk.  This is
                 NOT the same as the internal buffer, maintained by Free Pascal.  The function returns True
                 if the call was successful, false if an error occurred.

       Errors:    Errors are returned in LinuxError.

     See also:    fdOpen (187), fdClose (186), fdRead (188),fdWrite (190), fdTruncate (189), fdSeek (189)


                 For an example, see fdRead (188).
                 11.3.30         fdOpen

Declaration:      Function  fdOpen(PathName:String;flags:longint):longint;  Function  fdOpen(PathName:Pchar
                 ;flags:longint):longint;  Function  fdOpen(PathName:String;flags,mode:longint):longint;
                 Function  fdOpen(PathName:Pchar  ;flags,mode:longint):longint;

Description:      fdOpen opens a file in PathName with flags flags One of the following:

                 Open___RdOnly          File is opened Read-only.

                 Open___WrOnly          File is opened Write-only.

                 Open___RdWr         File is opened Read-Write.

                 The flags may beOR-ed with one of the following constants:

                 Open___Accmode           File is opened

                 Open___Creat        File is created if it doesn't exist.

                 Open___Excl      If the file is opened with Open__ Creat and it already exists, the call wil fail.

                 Open___NoCtty         If the file is a terminal device, it will NOT become the process' controlling
                       terminal.

                 Open___Trunc        If the file exists, it will be truncated.

                 Open___Append          the  file  is  opened  in  append  mode.  Before  each  write,  the  file  pointer  is
                       positioned at the end of the file.

                 Open___NonBlock           The  file  is  opened  in  non-blocking  mode.  No  operation  on  the  file  de-
                       scriptor will cause the calling process to wait till.

                 Open___NDelay         Idem as Open__ NonBlock

                 Open___Sync       The file is opened for synchronous IO. Any write operation on the file will not
                       return untill the data is physically written to disk.

                 Open___NoFollow          if  the  file  is  a  symbolic  link,  the  open  fails.  (linux  2.1.126  and  higher
                       only)

                 Open___Directory          if  the  file  is  not  a  directory,  the  open  fails.  (linux  2.1.126  and  higher
                       only)

                 PathName can be of type PChar or String.  The optional mode argument specifies the per-
                 missions  to  set  when  opening  the  file.   This  is  modified  by  the  umask  setting.   The  real
                 permissions are Mode  and  not  umask.  The return value of the function is the filedescriptor,
                 or a negative value if there was an error.

       Errors:    Errors are returned in LinuxError
                                                                                 187

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
     See also:    fdClose (186), fdRead (188), fdWrite (190),fdTruncate (189), fdFlush (187), fdSeek (189)


                 Listing:  linuxex/ex19.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example19      ;


                 {  Program       to    d e m o n s t r a t et h e fdOpen     ,  f d w r i t e and    f d C L o s e f u n c t i o n*
 * s.  }


                 Uses     l i n u x;


                 Const     L i n e  :   S t r i n g[ 8 0 ]  = ' T h i s|_|i s|_|e a s|y_|w r i t i n|g_|!;'


                 Var   FD    :   L o n g i n t;


                 b e g i n
                    FD  := fdOpen      ( ' T e s t. d a t' ,Open __WrOnly        or   Open __Creat      ) ;
                    i f  FD  >0   then
                        b e g i n
                        i f  l e n g t h(L i n e)<>   f d w r i t e( FD  ,L i n e [ 1 ] ,Length    ( L i n e) )  then
                           W r i t e l n ( ' E r r o r|_|when |_|w r i t i n|g_|to|_|f i l|e_|!)';
                        f d C l o s e(FD ) ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.31         fdRead

Declaration:      Function  fdRead  (fd:longint;var  buf;size:longint)  :    longint;

Description:      fdRead reads at most size bytes from the file descriptor fd, and stores them in buf.  The
                 function returns the number of bytes actually read, or -1 if an error occurred.  No checking
                 on the length of  buf is done.

       Errors:    Errors are returned in LinuxError.

     See also:    fdOpen (187), fdClose (186), fdWrite (190),fdTruncate (189), fdFlush (187), fdSeek (189)


                 Listing:  linuxex/ex20.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example20      ;


                 {  Program       to    d e m o n s t r a t et h e f d R e a d and     f d T r u n c a t ef u n c t i o n s.  }


                 Uses     l i n u x;


                 Const     Data     :   s t r i n g[ 1 0 ]  = ' 1 2 3 4 5 6 8 7 8 9 0;'


                 Var   FD    :   L o n g i n t;
                        l  :   l o n g i n t;


                 b e g i n
                    FD  := fdOpen     (' t e s t. d a t' , o p e n __w r o n l yor   o p e n __c r e a,to c t a l( 6 6 6 ) ) ;
                    i f   f d>0   then
                        b e g i n
                        {   F i l l f i l e  w i t h d a t a  }
                        f o r  l:=1    to   1 0   do
                           i f   f d W r i t e( FD  ,Data   [ 1 ] , 1 0 ) < > 1 0then
                               b e g i n



                                                                                 188

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                               w r i t e l n( ' E r r o r|_|when  |_|w r i t i n|g_|!)';
                               h a l t( 1 ) ;
                               end  ;
                        f d C l o s e(FD ) ;
                       FD  :=  fdOpen    ( ' t e s t.d a t ', o p e n __r d o n l)y;
                        {  Read     d a t a  a g a i n }
                        I f  FD >0    then
                           b e g i n
                           For    l :=1    to   5  do
                               i f  f d R e a d ( FD , Data   [ 1 ] , 1 0 ) < > 1 0then
                                  b e g i n
                                  W r i t e l n ( ' E r r o r|_|when |_|R e a d i n|g_|!)';
                                  Halt   ( 2 ) ;
                                  end  ;
                           f d C L o s e(FD  ) ;
                           {   T r u n c a t i n gf i l e  a t  6 0  b y t e s }
                           {   For    t r u n c a t i n,g  f i l e must     be   open     o r  w r i t e }
                           FD  := fdOpen     (' t e s t. d a t' , o p e n __w r o n l,yo c t a l( 6 6 6 ) ) ;
                           i f  FD  >0   then
                               b e g i n
                               i f  not    f d T r u n c a t(eFD  , 6 0 ) then
                                    W r i t e l n(' E r r o r|_|when |_|t r u n c a t i n|g_|!)';
                               f d C l o s e( FD  ) ;
                               end  ;
                           end   ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.32         fdSeek

Declaration:      Function  fdSeek  (fd,Pos,SeekType:longint)  :    longint;

Description:      fdSeek sets the current fileposition of file fd to Pos, starting from SeekType, which can be
                 one of the following:

                 Seek___Set     Pos is the absolute position in the file.

                 Seek___Cur       Pos is relative to the current position.

                 Seek___end      Pos is relative to the end of the file.

                 The function returns the new fileposition, or -1 of an error occurred.

       Errors:    Errors are returned in LinuxError.

     See also:    fdOpen (187), fdWrite (190), fdClose (186), fdRead (188),fdTruncate (189), fdFlush (187)


                 For an example, see fdOpen (187).
                 11.3.33         fdTruncate

Declaration:      Function  fdTruncate  (fd,size:longint)  :    boolean;

Description:      fdTruncate  sets  the  length  of  a  file  in  fd  on  size  bytes,  where  size  must  be  less  than
                 or  equal  to  the  current  length  of  the  file  in  fd.  The  function  returns  True  if  the  call  was
                 successful, false if an error occurred.

       Errors:    Errors are returned in LinuxError.

     See also:    fdOpen (187), fdClose (186), fdRead (188),fdWrite (190),fdFlush (187), fdSeek (189)



                                                                                 189

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.34         fdWrite

Declaration:      Function  fdWrite  (fd:longint;var  buf;size:longint)  :    longint;

Description:      fdWrite writes at most size bytes from buf to file descriptor fd.  The function returns the
                 number of bytes actually written, or -1 if an error occurred.

       Errors:    Errors are returned in LinuxError.

     See also:    fdOpen (187), fdClose (186), fdRead (188),fdTruncate (189), fdSeek (189), fdFlush (187)
                 11.3.35         FExpand

Declaration:      Function  FExpand  (Const  Path:    Pathstr)  :    pathstr;

Description:      Expands Path to a full path, starting from root, eliminating directory references such as .
                 and ..  from the result.

       Errors:    None

     See also:    BaseName (173),DirName (178)


                 Listing:  linuxex/ex45.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example45      ;


                 {  Program       to    d e m o n s t r a t et h e FExpand       f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( ' T h i s|_|program    |_|i s|_|i|n_|: |_|',FExpand   ( Paramstr      ( 0 ) ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.36         FLock

Declaration:      Function  Flock  (fd,mode  :    longint)  :    boolean;  Function  Flock  (var  T  :  text;mode
                 :    longint)  :    boolean;  Function  Flock  (var  F  :  File;mode  :    longint)  :    boolean;

Description:      FLock  implements  file  locking.   it  sets  or  removes  a  lock  on  the  file  F.  F  can  be  of  type
                 Text or File, or it can be a linux filedescriptor (a longint) Mode can be one of the following
                 constants :

                 LOCK___SH         sets a shared lock.

                 LOCK___EX          sets an exclusive lock.

                 LOCK___UN          unlocks the file.

                 LOCK___NB          This  can  be  OR-ed  together  with  the  other.  If  this  is  done  the  application
                       doesn't block when locking.

                 The function returns True if successful, False otherwise.

       Errors:    If an error occurs, it is reported in LinuxError.

     See also:    Fcntl (194), flock (2)



                                                                                 190

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.37         FNMatch

Declaration:      Function  FNMatch(const  Pattern,Name:string):Boolean;

Description:      FNMatch  returns  True  if  the  filename  in  Name  matches  the  wildcard  pattern  in  Pattern,
                 False otherwise.

                 Pattern can contain the wildcards * (match zero or more arbitrary characters) or ?  (match
                 a single character).

       Errors:    None.

     See also:    FSearch (191), FExpand (190)


                 Listing:  linuxex/ex69.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example69      ;


                 {  Program       to    d e m o n s t r a t et h e FNMatch       f u n c t i o n.  }


                 Uses     l i n u x;


                    Procedure         TestMatch      ( P a t t e r n,Name     :  S t r i n g) ;


                    b e g i n
                        Write     ( ' " ', Name   , ' " |_|') ;
                        I f  FNMatch       ( P a t t e r n,Name   )  then
                           Write     ( ' m a t c h e s')
                        e l s e
                           Write     ( ' d o e s|_|not |_|match   ') ;
                        W r i t e l n(' |_|" ',P a t t e r n,' " . ') ;
                    end   ;


                 b e g i n
                    TestMatch       ( ' * ', 'F i l e N a m e') ;
                    TestMatch       ( ' . * ',' F i l e N a m e') ;
                    TestMatch       ( ' *a * ', ' F i l e N a m e') ;
                    TestMatch       ( ' ?i l e* ' , 'F i l e N a m e') ;
                    TestMatch       ( ' ? ', 'F i l e N a m e') ;
                    TestMatch       ( ' . ? ',' F i l e N a m e') ;
                    TestMatch       ( ' ?a * ', ' F i l e N a m e') ;
                    TestMatch       ( ' ? ? *me ? ' ,' F i l e N a m e') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.38         FSearch

Declaration:      Function  FSearch  (Path  :    pathstr;DirList  :    string)  :    Pathstr;

Description:      Searches in DirList,  a colon separated list of directories,  for a file named Path.  It then
                 returns a path to the found file.

       Errors:    An empty string if no such file was found.

     See also:    BaseName (173), DirName (178), FExpand (190), FNMatch (191)


                 Listing:  linuxex/ex46.pp



                                                                                 191

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example46      ;


                 {  Program       to    d e m o n s t r a t et h e F S e a r c h f u n c t i o n.  }


                 Uses     l i n u x,s t r i n g s;


                 b e g i n
                    W r i t e l n ( ' l s|_|i s|_|i n|_|: |_|',F S e a r c(h' l s' , s t r p a s(G e t e n v('PATH    ' ) ) ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.39         FSplit

Declaration:      Procedure  FSplit(const  Path:PathStr;
                 Var  Dir:DirStr;Var  Name:NameStr;Var  Ext:ExtStr);

Description:      FSplit splits a full file name into 3 parts :  A Path, a Name and an extension (in ext).  The
                 extension is taken to be all letters after the last dot (.).

       Errors:    None.

     See also:    FSearch (191)


                 Listing:  linuxex/ex67.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example67      ;


                 u s e s  L i n u x;


                 {  Program       to    d e m o n s t r a t et h e F S p l i t  f u n c t i o n.  }


                 v a r
                    Path   , Name   , Ext    :  s t r i n g;


                 b e g i n
                    F S p l i t(ParamStr       ( 1 ) ,Path  , Name   , Ext  ) ;
                    WriteLn     ( ' S p l i t|_|',ParamStr      ( 1 ) ,' |_|i n: ') ;
                    WriteLn     ( ' Path   |_||_||_||_||_|:,|_|'Path) ;
                    WriteLn     ( ' Name   |_||_||_||_||_|:,|_|'Name) ;
                    WriteLn     ( ' E x t e n s i o n: |_|',Ext ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.40         FSStat

Declaration:      Function  FSStat  (Path  :    Pathstr;  Var  Info  :    statfs)  :    Boolean;  Function  FSStat
                 (Fd:longint;Var  Info:stat)  :    Boolean;

Description:      Return in Info information about the filesystem on which the file Path resides, or on which
                 the file with file descriptor fd resides.  Info is of type statfs.  The function returns True if
                 the call was succesfull, False if the call failed.

       Errors:    LinuxError is used to report errors.

                 sys___enotdir     A component of  Path is not a directory.

                 sys___einval    Invalid character in Path.

                 sys___enoent     Path does not exist.



                                                                                 192

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___eaccess     Search permission is denied for component in Path.

                 sys___eloop    A circular symbolic link was encountered in Path.

                 sys___eio  An error occurred while reading from the filesystem.

     See also:    FStat (193), LStat (208), statfs (2)


                 Listing:  linuxex/ex30.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       Example30      ;


                 {  Program       to    d e m o n s t r a t et h e F S S t a t  f u n c t i o n.  }


                 u s e s  l i n u x;


                 v a r  s  :   s t r i n g;
                        i n f o :   s t a t f s;


                 b e g i n
                    w r i t e l n ( ' I n f o|_|a b o u|t_|c u r r e n|t_|p a r t i t i|o_n|: |_|') ;
                    s :=  ' . ';
                    w h i l e  s<>  ' q'   do
                        b e g i n
                        i f  not    f s s t a t ( s , i n f o)  then
                             b e g i n
                             w r i t e l n(' F s t a t|_|f a i l e.d|_|E r r n|o_|: |_|',l i n u x e r r)o;r
                             h a l t  ( 1 ) ;
                             end  ;
                        w r i t e l n;
                        w r i t e l n( ' R e s u l t|_|o f|_|f s s t a|t_|on|_|f i l|e_|'','s ,' ' ' . ') ;
                        w r i t e l n( ' f s t y p e|_||_|: |_|',i n f.of s t y p)e;
                        w r i t e l n( ' b s i z e|_||_||_|:,|_|'i n f.ob s i z e) ;
                        w r i t e l n( ' b f r e e|_||_||_|:,|_|'i n f.ob f r e e) ;
                        w r i t e l n( ' b a v a i l|_||_|: |_|',i n f.ob a v a i)l;
                        w r i t e l n( '  f i l e s|_||_||_|:,|_|'i n.ffoi l e s) ;
                        w r i t e l n( ' f f r e e|_||_||_|:,|_|'i n f.of f r e e) ;
                        w r i t e l n( ' f s i d |_||_||_||_|:,|_|'i n.ffos i d) ;
                        w r i t e l n( ' Namelen      |_|: |_|',i n f.onamelen     ) ;
                        w r i t e ( ' Type   |_|name |_|o f|_|f i l|e_|to|_|do|_|f s s t a.t|_|(q|_|q u i t s) |_|:)';
                        r e a d l n ( s)
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.41         FStat

Declaration:      Function  FStat(Path:Pathstr;Var  Info:stat):Boolean;  Function  FStat(Fd:longint;Var
                 Info:stat):Boolean;  Function  FStat(var  F:Text;Var  Info:stat):Boolean;  Function
                 FStat(var  F:File;Var  Info:stat):Boolean;

Description:      FStat gets information about the file specified in one of the following:

                 Path   a file on the filesystem.

                 Fd  a valid file descriptor.

                 F an opened text file or untyped file.

                 and  stores  it  in  Info,  which  is  of  type  stat.   The  function  returns  True  if  the  call  was
                 succesfull, False if the call failed.



                                                                                 193

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    LinuxError is used to report errors.

                 sys___enoent     Path does not exist.

     See also:    FSStat (192), LStat (208), stat (2)


                 Listing:  linuxex/ex28.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       e x a m p l e 2;8


                 {  Program       to    d e m o n s t r a t et h e F S t a t  f u n c t i o n.  }


                 u s e s  l i n u x;


                 v a r  f  :   t e x t;
                        i  :   b y t e;
                        i n f o :   s t a t;


                 b e g i n
                    {   Make    a   f i l e }
                    a s s i g n ( f , ' t e s t.f i l' ) ;
                    r e w r i t e ( f ) ;
                    f o r  i :=1    to   1 0  do    w r i t e l n( f , ' T e s t l i n e|_|# |_|',i) ;
                    c l o s e (  f) ;
                    {  Do    t h e  c a l l  on   made     f i l e.  }
                    i f  not     f s t a t ( ' t e s t.f i l' , i n f o)  then
                          b e g i n
                          w r i t e l n('F s t a t|_|f a i l e.d|_|E r r n o|_|: |_|',l i n u x e r r)o;r
                          h a l t ( 1 ) ;
                         end   ;
                    w r i t e l n;
                    w r i t e l n ( ' R e s u l t|_|o|f_|f s t a|t_|on|_|f i l|e_|''t e s t.f i l' ' . ') ;
                    w r i t e l n ( ' I n o d e|_||_||_|:,|_|'i n f.oi n o) ;
                    w r i t e l n ( 'Mode    |_||_||_||_|:,|_|'i n.fmoode ) ;
                    w r i t e l n ( ' n l i n k|_||_||_|:,|_|'i n f.on l i n)k;
                    w r i t e l n ( ' u i d|_||_||_||_||_|:,|_|'i n.fuoi d) ;
                    w r i t e l n ( ' g i d|_||_||_||_||_|:,|_|'i n.fgoi d) ;
                    w r i t e l n ( ' r d e v|_||_||_||_|:,|_|'i n.frod e v) ;
                    w r i t e l n ( ' S i z e|_||_||_||_|:,|_|'i n.fsoi z e) ;
                    w r i t e l n ( ' B l k s i z e|_|: |_|',i n f.ob l k s z e) ;
                    w r i t e l n ( ' B l o c k s|_||_|: |_|',i n f.ob l o c k)s;
                    w r i t e l n ( ' a t i m e|_||_||_|:,|_|'i n f.oa t i m)e;
                    w r i t e l n ( ' mtime    |_||_||_|:,|_|'i n f.omtime  ) ;
                    w r i t e l n ( ' c t i m e|_||_||_|:,|_|'i n f.oc t i m)e;
                    {   Remove      f i l e }
                    e r a s e (  f) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.42         Fcntl

Declaration:      Function  Fcntl(Fd:longint;Cmd:Integer):integer;  Function  Fcntl(var  Fd:Text;Cmd:Integer):integer;

Description:      Read a file's attributes.  Fd is an assigned file, or a valid file descriptor.  Cmd speciefies what
                 to do, and is one of the following:

                 F___GetFd      Read the close__ on__ exec flag.  If the low-order bit is 0, then the file will remain
                       open across execve calls.
                                                                                 194

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 F___GetFl     Read the descriptor's flags.

                 F___GetOwn        Get the Process ID of the owner of a socket.

       Errors:    LinuxError is used to report errors.

                 sys___ebadf    Fd has a bad file descriptor.

     See also:    Fcntl (195), Fcntl (2)
                 11.3.43         Fcntl

Declaration:      Procedure  Fcntl  (Fd  :    text,  Cmd  :    Integer;  Arg  :    longint);  Procedure  Fcntl
                 (Fd:longint;Cmd:longint;Arg:Longint);

Description:      Read or Set a file's attributes.  Fd is an assigned file or a valid file descriptor.  Cmd speciefies
                 what to do, and is one of the following:

                 F___SetFd     Set the close__ on__ exec flag of  Fd.  (only the least siginificant bit is used).

                 F___GetLk     Return the flock record that prevents this process from obtaining the lock,  or
                       set the l__ type field of the lock of there is no obstruction.  Arg is a pointer to a flock
                       record.

                 F___SetLk     Set the lock or clear it (depending on l__ type in the flock structure).  if the lock
                       is held by another process, an error occurs.

                 F___GetLkw       Same as for F___Setlk, but wait until the lock is released.

                 F___SetOwn       Set the Process or process group that owns a socket.

       Errors:    LinuxError is used to report errors.

                 sys___ebadf    Fd has a bad file descriptor.

                 sys___eagain or sys___eaccess            For F___SetLk, if the lock is held by another process.

     See also:    Fcntl (194), Fcntl (2) , seefFLock
                 11.3.44         Fork

Declaration:      Function  Fork  :    Longint;

Description:      Fork creates a child process which is a copy of the parent process.  Fork returns the process
                 ID in the parent process, and zero in the child's process.  (you can get the parent's PID with
                 GetPPid (201)).

       Errors:    On error, -1 is returned to the parent, and no child is created.

                 sys___eagain     Not enough memory to create child process.

     See also:    Execve (184), Clone (176), fork (2)
                 11.3.45         FRename

Declaration:      Function  FReName  (OldName,NewName  :    Pchar)  :    Boolean;  Function  FReName  (OldName,NewName
                 :    String)  :    Boolean;

                                                                                 195

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      FRename  renames  the  file  OldName  to  NewName.   NewName  can  be  in  a  different  directory
                 than OldName, but it cannot be on another partition (device).  Any existing file on the new
                 location will be replaced.

                 If the operation fails, then the OldName file will be preserved.

                 The function returns True on succes, False on failure.

       Errors:    On error, errors are reported in LinuxError.  Possible errors include:

                 sys___eisdir   NewName exists and is a directory, but OldName is not a directory.

                 sys___exdev     NewName and OldName are on different devices.

                 sys___enotempty or sys___eexist               NewName is an existing, non-empty directory.

                 sys___ebusy     OldName or NewName is a directory and is in use by another process.

                 sys___einval    NewName is part of  OldName.

                 sys___emlink     OldPath  or  NewPath  already  have  tha  maximum  amount  of  links  pointing  to
                       them.

                 sys___enotdir     part of  OldName or NewName is not directory.

                 sys___efault    For the pchar case:  One of the pointers points to an invalid address.

                 sys___eaccess     access is denied when attempting to move the file.

                 sys___enametoolong           Either OldName or NewName is too long.

                 sys___enoent     a directory component in OldName or NewName didn't exist.

                 sys___enomem        not enough kernel memory.

                 sys___erofs   NewName or OldName is on a read-only file system.

                 sys___eloop    too many symbolic links were encountered trying to expand OldName or NewName

                 sys___enospc     the filesystem has no room for the new directory entry.

     See also:    UnLink (232)
                 11.3.46         GetDate

Declaration:      Procedure  GetDate  (Var  Year,  Month,  Day  :    Word)  ;

Description:      Returns the current date.

       Errors:    None

     See also:    GetEpochTime (199), GetTime (202), GetDateTime (197), EpochToLocal (180)


                 Listing:  linuxex/ex6.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;


                 {  Program       to    d e m o n s t r a t et h e GetDate       f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    Year   ,  Month    ,  Day    :   Word   ;


                 b e g i n
                   GetDate      ( Year   ,   Month    ,  Day  ) ;
                   W r i t e l n( ' Date   |_|: |_|',Day : 2 ,' / ', Month    : 2 ,' / ', Year   : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 196

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.47         GetDateTime

Declaration:      Procedure  GetDateTime(Var  Year,Month,Day,hour,minute,second:Word);

Description:      Returns  the  current  date  and  time.  The  time  is  corrected  for  the  local  time  zone.  This
                 procedure is equivalent to the GetDate (196) and GetTime calls.

       Errors:    None

     See also:    GetEpochTime (199), GetTime (202), EpochToLocal (180), GetDate (196)


                 Listing:  linuxex/ex60.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;


                 {  Program       to    d e m o n s t r a t et h e GetDateTime          f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    Year   ,  Month    ,  Day   ,  Hour   ,  min   ,  s e c  :   Word   ;


                 b e g i n
                  GetDateTime          ( Year   ,  Month     ,  Day  ,  Hour    ,  min  ,   s e c) ;
                   W r i t e l n( ' Date   |_|: |_|',Day : 2 ,' / ', Month    : 2 ,' / ', Year   : 4 ) ;
                   W r i t e l n( ' Time   |_|: |_|',Hour  : 2 ,' : ', Min  : 2 , ' : ',Sec   : 2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.48         GetDomainName

Declaration:      Function  GetDomainName  :    String;

Description:      Get the domain name of the machine on which the process is running.  An empty string is
                 returned if the domain is not set.

       Errors:    None.

     See also:    GetHostName (200),seemGetdomainname2


                 Listing:  linuxex/ex39.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example39      ;


                 {  Program       to    d e m o n s t r a t et h e GetDomainName            f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( ' Domain    |_|name  |_|o f|_|t h i|s_|machine   |_|i s|_|: |_|',GetDomainName       ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.49         GetEGid

Declaration:      Function  GetEGid  :    Longint;

Description:      Get the effective group ID of the currently running process.

       Errors:    None.



                                                                                 197

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
     See also:    GetGid (200), getegid (2)


                 Listing:  linuxex/ex18.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example18      ;


                 {  Program       to    d e m o n s t r a t et h e G e t G i d and    GetEGid        f u n c t i o n.s }


                 Uses     l i n u x;


                 b e g i n
                   w r i t e l n( ' Group    |_|I d|_|= |_|',g e t g i,d' |_|E f f e c t i|v_e|g r o u|p_|I|d_|= |_|',g e t e g)i;d
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.50         GetEUid

Declaration:      Function  GetEUid  :    Longint;

Description:      Get the effective user ID of the currently running process.

       Errors:    None.

     See also:    GetEUid (198), geteuid (2)


                 Listing:  linuxex/ex17.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example17      ;


                 {  Program       to    d e m o n s t r a t et h e GetUid      and    GetEUid        f u n c t i o n.s }


                 Uses     l i n u x;


                 b e g i n
                    w r i t e l n ( ' U s e r|_|I d|_|= |_|',g e t u i,d' |_|E f f e c t i|v_e|u s e|r_|I|d_|= |_|',g e t e u)i;d
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.51         GetEnv

Declaration:      Function  GetEnv  (P  :  String)  :    PChar;

Description:      Returns  the  value  of  the  environment  variable  in  P.  If  the  variable  is  not  defined,  nil  is
                 returned.   The  value  of  the  environment  variable  may  be  the  empty  string.   A  PChar  is
                 returned  to  accomodate  for  strings  longer  than  255  bytes,  TERMCAP  and  LS__ COLORS,  for
                 instance.

       Errors:    None.

     See also:    sh (1) , csh (1)


                 Listing:  linuxex/ex41.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example41      ;


                 {  Program       to    d e m o n s t r a t et h e GetEnv       f u n c t i o n.  }

                                                                                 198

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( ' Path   |_|i s|_|: |_|',G e t e n(v'PATH   ') ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.52         GetEpochTime

Declaration:      Function  GetEpochTime  :    longint;

Description:      returns  the  number  of  seconds  since  00:00:00  gmt,  january  1,  1970.  it  is  adjusted  to  the
                 local time zone, but not to DST.

       Errors:    no errors

     See also:    EpochToLocal (180), GetTime (202), time (2)


                 Listing:  linuxex/ex1.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;


                 {  Program       to    d e m o n s t r a t et h e GetEpochTime           f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    Write     (  'S e c s|_|p a s t|_|t h|e_|s t a r|t_|o|f_|t h|e_|Epoch |_|( 0 0 : 0 0 |_|1 / 1 / 1 9 8 0 ) |_|:)*
 *|_|';
                    W r i t e l n ( GetEpochTime         ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.53         GetFS

Declaration:      Function  GetFS  (Var  F  :  Any  File  Type)  :    Longint;

Description:      GetFS returns the file selector that the kernel provided for your file.  In principle you don'
                 need this file selector.  Only for some calls it is needed, such as the Select (220) call or so.

       Errors:    In case the file was not opened, then -1 is returned.

     See also:    Select (220)


                 Listing:  linuxex/ex34.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example33      ;


                 {  Program       to    d e m o n s t r a t et h e S e l e c t T e x t f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    t v  :  TimeVal      ;


                 b e g i n
                    W r i t e l n ( ' P r e s s|_|t h|e_|<ENTER  >|_|to  |_|c o n t i n u|e_|t h|e_|program  . ' ) ;
                    {   Wait     u n t i l F i l e  d e s c r i p t o r0  ( = I n p u t)  c h a n g e s}
                    S e l e c t T e x t( I n p u t, n i l) ;
                    {   Get    r i d  o f < ENTER    >   i n  b u f f e r }



                                                                                 199

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    r e a d l n;
                    W r i t e l n ( ' P r e s s|_|<ENTER  >|_|key  |_|i n|_|l e s|s_|t h a|n_|2s|_|e c o n d.s. . ') ;
                    t v . s e c: = 2 ;
                    t v . u s e c: = 0 ;
                    i f   S e l e c t T e x t(I n p u t, @tv  )>0    then
                        W r i t e l n( ' Thank    |_|you |_|! ')
                    e l s e
                        W r i t e l n( ' Too  |_|l a t e|_|!)';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.54         GetGid

Declaration:      Function  GetGid  :    Longint;

Description:      Get the real group ID of the currently running process.

       Errors:    None.

     See also:    GetEGid (197), getgid (2)


                 Listing:  linuxex/ex18.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example18      ;


                 {  Program       to    d e m o n s t r a t et h e G e t G i d and    GetEGid        f u n c t i o n.s }


                 Uses     l i n u x;


                 b e g i n
                   w r i t e l n( ' Group    |_|I d|_|= |_|',g e t g i,d' |_|E f f e c t i|v_e|g r o u|p_|I|d_|= |_|',g e t e g)i;d
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.55         GetHostName

Declaration:      Function  GetHostName  :    String;

Description:      Get  the  hostname  of  the  machine  on  which  the  process  is  running.   An  empty  string  is
                 returned if hostname is not set.

       Errors:    None.

     See also:    GetDomainName (197),seemGethostname2


                 Listing:  linuxex/ex40.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example40      ;


                 {  Program       to    d e m o n s t r a t et h e GetHostName          f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( 'Name    |_|o f|_|t h i|s_|machine   |_|i s|_|: |_|',GetHostName      ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________


                                                                                 200

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.56         GetLocalTimezone

Declaration:      procedure  GetLocalTimezone(timer:longint;var  leap__ correct,leap__ hit:longint);
                 procedure  GetLocalTimezone(timer:longint);

Description:      GetLocalTimeZone returns the local timezone information.  It also initializes the TZSeconds
                 variable, which is used to correct the epoch time to local time.

                 There should never be any need to call this function directly.  It is called by the initialization
                 routines of the Linux unit.

     See also:    GetTimezoneFile (203), ReadTimezoneFile (219)
                 11.3.57         GetPid

Declaration:      Function  GetPid  :    Longint;

Description:      Get the Process ID of the currently running process.

       Errors:    None.

     See also:    GetPPid (201), getpid (2)


                 Listing:  linuxex/ex16.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example16      ;


                 {  Program       to    d e m o n s t r a t et h e G e t P i d,  GetPPid       f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( ' P r o c e s s|_|I|d_|= |_|',g e t p i,d' |_|P a r e n|t_|p r o c e|s_s|I|d_|= |_|',g e t p p)*
 *i;d
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.58         GetPPid

Declaration:      Function  GetPPid  :    Longint;

Description:      Get the Process ID of the parent process.

       Errors:    None.

     See also:    GetPid (201), getppid (2)


                 Listing:  linuxex/ex16.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example16      ;


                 {  Program       to    d e m o n s t r a t et h e G e t P i d,  GetPPid       f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( ' P r o c e s s|_|I|d_|= |_|',g e t p i,d' |_|P a r e n|t_|p r o c e|s_s|I|d_|= |_|',g e t p p)*
 *i;d
                _end__.____________________________________________________________________________________________________________*
 *_____________

                                                                                 201

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.59         GetPriority

Declaration:      Function  GetPriority  (Which,Who  :    Integer)  :    Integer;

Description:      GetPriority returns the priority with which a process is running.  Which process(es) is deter-
                 mined by the Which and Who variables.  Which can be one of the pre-defined Prio__ Process,
                 Prio__ PGrp,  Prio__ User, in which case Who is the process ID, Process group ID or User ID,
                 respectively.

       Errors:    Error checking must be done on LinuxError, since a priority can be negative.

                 sys___esrch    No process found using which and who.

                 sys___einval    Which was not one of  Prio__ Process,  Prio__ Grp  or  Prio__ User.

     See also:    SetPriority (221), Nice (213), Getpriority (2)


                 For an example, see Nice (213).
                 11.3.60         GetTime

Declaration:      procedure  GetTime(var  hour,min,sec,msec,usec:word);  procedure  GetTime(var  hour,min,sec,sec100:word);
                 procedure  GetTime(var  hour,min,sec:word);

Description:      Returns the current time of the day, adjusted to local time.  Upon return, the parameters
                 are filled with

                 hour   Hours since 00:00 today.

                 min   minutes in current hour.

                 sec seconds in current minute.

                 sec100    hundreds of seconds in current second.

                 msec   milliseconds in current second.

                 usec  microseconds in current second.

       Errors:    None

     See also:    GetEpochTime (199), GetDate (196), GetDateTime (197), EpochToLocal (180)


                 Listing:  linuxex/ex5.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example5      ;


                 {  Program       to    d e m o n s t r a t et h e GetTime       f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    Hour   ,  Minute     ,  Second      :   Word   ;


                 b e g i n
                    GetTime       ( Hour   ,  Minute     ,  Second     ) ;
                    W r i t e l n ( ' Time   |_|: |_|',Hour  : 2 ,' : ', Minute    : 2 , ' : ',Second     : 2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________


                                                                                 202

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.61         GetTimeOfDay

Declaration:      Procedure  GetTimeOfDay(var  tv:timeval);

Description:      GetTimeOfDay  returns  the  number  of  seconds  since  00:00,  January  1  1970,  GMT  in  a
                 timeval  record.   This  time  NOT  corrected  any  way,  not  taking  into  account  timezones,
                 daylight savings time and so on.

                 It is simply a wrapper to the kernel system call.  To get the local time, GetTime (202).

       Errors:    None.

     See also:    GetTime (202), GetTimeOfDay (203)
                 11.3.62         GetTimeOfDay

Declaration:      Function  GetTimeOfDay:longint;

Description:      GetTimeOfDay returns the number of seconds since 00:00, January 1 1970, GMT. This time
                 NOT corrected any way, not taking into account timezones, daylight savings time and so on.

                 It is simply a wrapper to the kernel system call.  To get the local time, GetTime (202).

       Errors:    None.

     See also:    GetTimeOfDay (203), GetTime (202)
                 11.3.63         GetTimezoneFile

Declaration:      function  GetTimezoneFile:string;

Description:      GetTimezoneFile returns the location of the current timezone file.  The location of file is
                 determined as follows:

                     1.If  /etc/timezone exists, it is read, and the contents of this file is returned.  This should
                       work on Debian systems.

                     2.If  /usr/lib/zoneinfo/localtime  exists,  then  it  is  returned.  (this  file  is  a  symlink  to  the
                       timezone file on SuSE systems)

                     3.If  /etc/localtime exists, then it is returned.  (this file is a symlink to the timezone file
                       on RedHat systems)

       Errors:    If no file was found, an empty string is returned.

     See also:    ReadTimezoneFile (219)
                 11.3.64         GetUid

Declaration:      Function  GetUid  :    Longint;

Description:      Get the real user ID of the currently running process.

       Errors:    None.

     See also:    GetEUid (198), getuid (2)


                 Listing:  linuxex/ex17.pp


                                                                                 203

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example17      ;


                 {  Program       to    d e m o n s t r a t et h e GetUid      and    GetEUid        f u n c t i o n.s }


                 Uses     l i n u x;


                 b e g i n
                    w r i t e l n ( ' U s e r|_|I d|_|= |_|',g e t u i,d' |_|E f f e c t i|v_e|u s e|r_|I|d_|= |_|',g e t e u)i;d
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.65         Glob

Declaration:      Function  Glob  (Const  Path  :    Pathstr)  :    PGlob;

Description:      Glob  returns  a  pointer  to  a  glob  structure  which  contains  all  filenames  which  exist  and
                 match the pattern in Path.  The pattern can contain wildcard characters, which have their
                 usual meaning.

       Errors:    Returns nil on error, and LinuxError is set.

                 sys___enomem        No memory on heap for glob structure.

                 others   As returned by the opendir call, and sys__ readdir.

     See also:    GlobFree (204), Glob (3)


                 Listing:  linuxex/ex49.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example49      ;


                 {  Program       to    d e m o n s t r a t et h e Glob     and    G l o b F r e e f u n c t i o n s.  }


                 Uses     l i n u x;


                 Var    G1 , G2   :   PGlob   ;


                 b e g i n
                    G1  := Glob     ( ' * ') ;
                    i f   L i n u x E r r o=r0  then
                        b e g i n
                        G2 := G1  ;
                        W r i t e l n( ' F i l e s|_|i n|_|t h i|s_|d i r e c t o r|y_|:)|_|';
                        While     g2 <>  N i l  do
                           b e g i n
                           W r i t e l n ( g2 ^ . name   ) ;
                           g2  := g2  ^ .n e x t;
                           end   ;
                        G l o b F r e e( g1  ) ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.66         GlobFree

Declaration:      Procedure  GlobFree  (Var  P  :  Pglob);

Description:      Releases the memory, occupied by a pglob structure.  P is set to nil.



                                                                                 204

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    None

     See also:    Glob (204)


                 For an example, see Glob (204).
                 11.3.67         IOCtl

Declaration:      Procedure  IOCtl  (Handle,Ndx:    Longint;  Data:    Pointer);

Description:      This  is  a  general  interface  to  the  Unix/  linux  ioctl  call.  It  performs  various  operations
                 on the filedescriptor Handle.  Ndx describes the operation to perform.  Data points to data
                 needed for the Ndx function.  The structure of this data is function-dependent, so we don't
                 elaborate on this here.  For more information on this, see various manual pages under linux.

       Errors:    Errors are reported in LinuxError.  They are very dependent on the used function, that's
                 why we don't list them here

     See also:    ioctl (2)


                 Listing:  linuxex/ex54.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example54      ;


                 u s e s  L i n u x;


                 {  Program       to    d e m o n s t r a t et h e I O C t l  f u n c t i o n.  }


                 v a r
                    t i o s  :  T e r m i o s;
                 b e g i n
                    I O C t l( 1 ,TCGETS     , @ t i o s) ;
                    WriteLn     ( ' I n p u t|_|F l a g|s_||_|:$|_|',h e x s t(rt i o s.c __i f l a g, 8 ) ) ;
                    WriteLn     ( ' Output    |_|F l a g s|_|:$|_|',h e x s t r(t i o s.c __o f l a g, 8 ) ) ;
                    WriteLn     ( ' L i n e|_|F l a g s|_||_||_|:$|_|',h e x s(ttri o s.c __l f l a g, 8 ) ) ;
                    WriteLn     ( ' C o n t r o l|_|F l a g:s|_|$',h e x s t r( t i o s.c __c f l a g, 8 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.68         IOperm

Declaration:      Function  IOperm  (From,Num  :    Cadinal;  Value  :    Longint)  :    boolean;

Description:      IOperm  sets  permissions  on  Num  ports  starting  with  port  From  to  Value.   The  function
                 returns True if the call was successfull, False otherwise.  Remark:

                      oThis works ONLY as root.

                      oOnly the first 0x03ff ports can be set.

                      oWhen doing a Fork (195), the permissions are reset.  When doing a Execve (184) they
                       are kept.

       Errors:    Errors are returned in LinuxError

     See also:    ioperm (2)



                                                                                 205

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.69         IsATTY

Declaration:      Function  IsATTY  (var  f)  :    Boolean;

Description:      Check if the filehandle described by f is a terminal.  f can be of type

                     1.longint for file handles;

                     2.Text for text variables such as input etc.

                 Returns True if  f is a terminal, False otherwise.

       Errors:    No errors are reported

     See also:    IOCtl (205),TTYName (231)
                 11.3.70         S___ISBLK

Declaration:      Function  S__ ISBLK  (m:integer)  :    boolean;

Description:      S__ ISBLK checks the file mode m to see whether the file is a block device file.  If so it returns
                 True.

       Errors:    FStat  (193),  S__ ISLNK  (207),  S__ ISREG  (207),  S__ ISDIR  (206),  S__ ISCHR  (206),  S__ ISFIFO
                 (206), S__ ISSOCK (207)

     See also:    ISLNK.
                 11.3.71         S___ISCHR

Declaration:      Function  S__ ISCHR  (m:integer)  :    boolean;

Description:      S__ ISCHR checks the file mode m to see whether the file is a character device file.  If so it
                 returns True.

       Errors:    FStat  (193),  S__ ISLNK  (207),  S__ ISREG  (207),  S__ ISDIR  (206),  S__ ISBLK  (206),  S__ ISFIFO
                 (206), S__ ISSOCK (207)

     See also:    ISLNK.
                 11.3.72         S___ISDIR

Declaration:      Function  S__ ISDIR  (m:integer)  :    boolean;

Description:      S__ ISDIR checks the file mode m to see whether the file is a directory.  If so it returns True

       Errors:    FStat  (193),  S__ ISLNK  (207),  S__ ISREG  (207),  S__ ISCHR  (206),  S__ ISBLK  (206),  S__ ISFIFO
                 (206), S__ ISSOCK (207)

     See also:    ISLNK.
                 11.3.73         S___ISFIFO

Declaration:      Function  S__ ISFIFO  (m:integer)  :    boolean;

Description:      S__ ISFIFO checks the file mode m to see whether the file is a fifo (a named pipe).  If so it
                 returns True.

       Errors:    FStat  (193),  S__ ISLNK  (207),  S__ ISREG  (207),  S__ ISDIR  (206),  S__ ISCHR  (206),  S__ ISBLK
                 (206), S__ ISSOCK (207)

     See also:    ISLNK.



                                                                                 206

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.74         S___ISLNK

Declaration:      Function  S__ ISLNK  (m:integer)  :    boolean;

Description:      S__ ISLNK checks the file mode m to see whether the file is a symbolic link.  If so it returns
                 True

       Errors:    FStat  (193),  S__ ISREG  (207),  S__ ISDIR  (206),  S__ ISCHR  (206),  S__ ISBLK  (206),  S__ ISFIFO
                 (206), S__ ISSOCK (207)

     See also:


                 Listing:  linuxex/ex53.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example53      ;


                 {  Program       to    d e m o n s t r a t et h e S__ISLNK      f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    I n f o :   S t a t;


                 b e g i n
                    i f   L S t a t ( p a r a m s t r( 1 ) ,i n f o) then
                        b e g i n
                        i f  S__ISLNK    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|l i n'k) ;
                        i f  S__ISREG    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|r e g u l|a_r|f i l'e) ;
                        i f  S __ISDIR   ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|d i r e c t o'r)y;
                        i f  S__ISCHR    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|c h a r a c t|e_r|d e v i|c_e|f i l'e) ;
                        i f  S__ISBLK    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|b l o c|k_|d e v i|c_e|f i l'e) ;
                        i f  S __ISFIFO    ( i n f o.mode   )   then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|named |_|p i p e|_|(FIFO ) ' ) ;
                        i f  S__ISSOCK     ( i n f o.mode   )   then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|s o c k e't) ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.75         S___ISREG

Declaration:      Function  S__ ISREG  (m:integer)  :    boolean;

Description:      S__ ISREG checks the file mode m to see whether the file is a regular file.  If so it returns True

       Errors:    FStat  (193),  S__ ISLNK  (207),  S__ ISDIR  (206),  S__ ISCHR  (206),  S__ ISBLK  (206),  S__ ISFIFO
                 (206), S__ ISSOCK (207)

     See also:    ISLNK.
                 11.3.76         S___ISSOCK

Declaration:      Function  S__ ISSOCK  (m:integer)  :    boolean;

Description:      S__ ISSOCK checks the file mode m to see whether the file is a socket.  If so it returns True.



                                                                                 207

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    FStat  (193),  S__ ISLNK  (207),  S__ ISREG  (207),  S__ ISDIR  (206),  S__ ISCHR  (206),  S__ ISBLK
                 (206), S__ ISFIFO (206)

     See also:    ISLNK.
                 11.3.77         Kill

Declaration:      Function  Kill  (Pid  :    Longint;  Sig  :    Integer)  :    Integer;

Description:      Send a signal Sig to a process or process group.  If  Pid>0 then the signal is sent to Pid,
                 if it equals -1,  then the signal is sent to all processes except process 1.  If  Pid<-1 then the
                 signal is sent to process group -Pid.  The return value is zero,  except in case three,  where
                 the return value is the number of processes to which the signal was sent.

       Errors:    LinuxError is used to report errors:

                 sys___einval    An invalid signal is sent.

                 sys___esrch    The Pid or process group don't exist.

                 sys___eperm      The effective userid of the current process doesn't math the one of process Pid.

     See also:    SigAction (222), Signal (225), Kill (2)
                 11.3.78         LStat

Declaration:      Function  LStat  (Path  :    Pathstr;  Var  Info  :    stat)  :    Boolean;

Description:      LStat gets information about the link specified in Path, and stores it in Info, which is of
                 type stat.  Contrary to FStat, it stores information about the link, not about the file the
                 link points to.  The function returns True if the call was succesfull, False if the call failed.

       Errors:    LinuxError is used to report errors.

                 sys___enoent     Path does not exist.

     See also:    FStat (193), FSStat (192), stat (2)


                 Listing:  linuxex/ex29.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       e x a m p l e 2;9


                 {  Program       to    d e m o n s t r a t et h e L S t a t  f u n c t i o n.  }


                 u s e s  l i n u x;


                 v a r  f  :   t e x t;
                        i  :   b y t e;
                        i n f o :   s t a t;


                 b e g i n
                    {   Make    a   f i l e }
                    a s s i g n ( f , ' t e s t.f i l' ) ;
                    r e w r i t e ( f ) ;
                    f o r  i :=1    to   1 0  do    w r i t e l n( f , ' T e s t l i n e|_|# |_|',i) ;
                    c l o s e (  f) ;
                    {  Do    t h e  c a l l  on   made     f i l e.  }
                    i f  not     f s t a t ( ' t e s t.f i l' , i n f o)  then
                          b e g i n



                                                                                 208

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                          w r i t e l n('F s t a t|_|f a i l e.d|_|E r r n o|_|: |_|',l i n u x e r r)o;r
                          h a l t ( 1 ) ;
                         end   ;
                    w r i t e l n;
                    w r i t e l n ( ' R e s u l t|_|o|f_|f s t a|t_|on|_|f i l|e_|''t e s t.f i l' ' . ') ;
                    w r i t e l n ( ' I n o d e|_||_||_|:,|_|'i n f.oi n o) ;
                    w r i t e l n ( 'Mode    |_||_||_||_|:,|_|'i n.fmoode ) ;
                    w r i t e l n ( ' n l i n k|_||_||_|:,|_|'i n f.on l i n)k;
                    w r i t e l n ( ' u i d|_||_||_||_||_|:,|_|'i n.fuoi d) ;
                    w r i t e l n ( ' g i d|_||_||_||_||_|:,|_|'i n.fgoi d) ;
                    w r i t e l n ( ' r d e v|_||_||_||_|:,|_|'i n.frod e v) ;
                    w r i t e l n ( ' S i z e|_||_||_||_|:,|_|'i n.fsoi z e) ;
                    w r i t e l n ( ' B l k s i z e|_|: |_|',i n f.ob l k s z e) ;
                    w r i t e l n ( ' B l o c k s|_||_|: |_|',i n f.ob l o c k)s;
                    w r i t e l n ( ' a t i m e|_||_||_|:,|_|'i n f.oa t i m)e;
                    w r i t e l n ( ' mtime    |_||_||_|:,|_|'i n f.omtime  ) ;
                    w r i t e l n ( ' c t i m e|_||_||_|:,|_|'i n f.oc t i m)e;


                    I f  not    SymLink       ( ' t e s t. f i l' ,' t e s t. l n k' )  then
                        w r i t e l n( ' L i n k|_|f a i l e d|_|!E|_|r r n|o_|:,'l i n u x e r r o)r;


                    i f  not     l s t a t ( ' t e s t.l n k' , i n f o)  then
                          b e g i n
                          w r i t e l n('L S t a t|_|f a i l e.d|_|E r r n o|_|: |_|',l i n u x e r r)o;r
                          h a l t ( 1 ) ;
                         end   ;
                    w r i t e l n;
                    w r i t e l n ( ' R e s u l t|_|o|f_|f s t a|t_|on|_|f i l|e_|''t e s t.l n k' ' . ') ;
                    w r i t e l n ( ' I n o d e|_||_||_|:,|_|'i n f.oi n o) ;
                    w r i t e l n ( 'Mode    |_||_||_||_|:,|_|'i n.fmoode ) ;
                    w r i t e l n ( ' n l i n k|_||_||_|:,|_|'i n f.on l i n)k;
                    w r i t e l n ( ' u i d|_||_||_||_||_|:,|_|'i n.fuoi d) ;
                    w r i t e l n ( ' g i d|_||_||_||_||_|:,|_|'i n.fgoi d) ;
                    w r i t e l n ( ' r d e v|_||_||_||_|:,|_|'i n.frod e v) ;
                    w r i t e l n ( ' S i z e|_||_||_||_|:,|_|'i n.fsoi z e) ;
                    w r i t e l n ( ' B l k s i z e|_|: |_|',i n f.ob l k s z e) ;
                    w r i t e l n ( ' B l o c k s|_||_|: |_|',i n f.ob l o c k)s;
                    w r i t e l n ( ' a t i m e|_||_||_|:,|_|'i n f.oa t i m)e;
                    w r i t e l n ( ' mtime    |_||_||_|:,|_|'i n f.omtime  ) ;
                    w r i t e l n ( ' c t i m e|_||_||_|:,|_|'i n f.oc t i m)e;
                    {   Remove      f i l e  and    l i n k }
                    e r a s e (  f) ;
                    u n l i n k ( ' t e s t. l n k' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.79         Link

Declaration:      Function  Link  (OldPath,NewPath  :    pathstr)  :    Boolean;

Description:      Link makes NewPath point to the same file als OldPath.  The two files then have the same
                 inode  number.  This  is  known  as  a  'hard'  link.  The  function  returns  True  if  the  call  was
                 succesfull, False if the call failed.

       Errors:    Errors are returned in LinuxError.

                 sys___exdev     OldPath and NewPath are not on the same filesystem.

                 sys___eperm      The filesystem containing oldpath and newpath doesn't support linking files.
                                                                                 209

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___eaccess     Write access for the directory containing Newpath is disallowed, or one of the
                       directories in OldPath or NewPath has no search (=execute) permission.

                 sys___enoent     A directory entry in OldPath or NewPath does not exist or is a symbolic link
                       pointing to a non-existent directory.

                 sys___enotdir     A directory entry in OldPath or NewPath is nor a directory.

                 sys___enomem        Insufficient kernel memory.

                 sys___erofs   The files are on a read-only filesystem.

                 sys___eexist    NewPath already exists.

                 sys___emlink     OldPath has reached maximal link count.

                 sys___eloop    OldPath or NewPath has a reference to a circular symbolic link, i.e.  a symbolic
                       link, whose expansion points to itself.

                 sys___enospc     The device containing NewPath has no room for anothe entry.

                 sys___eperm      OldPath points to .  or ..  of a directory.

     See also:    SymLink (226), UnLink (232), Link (2)


                 Listing:  linuxex/ex21.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example21      ;


                 {  Program       to    d e m o n s t r a t et h e L i n k  and    UnLink      f u n c t i o n s.  }


                 Uses     l i n u x;


                 Var    F  :   Text   ;
                        S  :   S t r i n g;
                 b e g i n
                    A s s i g n ( F , ' t e s t.t x t' ) ;
                    R e w r i t e ( F ) ;
                    W r i t e l n ( F ,' T h i s|_|i s|_|w r i t t e|n_|to|_|t e s.tt x t') ;
                    C l o s e( f ) ;
                    {   new  . t x t  and    t e s t.t x t  a r e  now    t h e  same     f i l e }
                    i f  not     L i n k ( ' t e s t.t x t ', ' new  . t x t' )  then
                        w r i t e l n( ' E r r o r|_|when  |_|l i n k i n|g_|!)';
                    {   Removing        t e s t.t x t   s t i l l l e a v e s new  . t x t }
                    I f  not     U n l i n k( ' t e s t. t x t' )  then
                        W r i t e l n( ' E r r o r|_|when  |_|u n l i n k i n|g_|!)';
                    A s s i g n ( f , 'new   . t x t' ) ;
                    Reset     ( F ) ;
                    While      not   EOF   ( f )  do
                        b e g i n
                        Readln    ( F ,S ) ;
                        W r i t e l n( ' > |_|',s ) ;
                        end  ;
                   C l o s e ( f ) ;
                   {  Remove      new  . t x t  a l s o }
                   I f  not    U n l i n k ( 'new   .t x t ')   then
                      W r i t e l n ( ' E r r o r|_|when |_|u n l i n k i n|g_|!)';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.80         LocalToEpoch

Declaration:      Function  LocalToEpoch  (Year,Month,Day,Hour,Minute,Second  :    Word)  :    longint;



                                                                                 210

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      Converts the Local time to epoch time (=Number of seconds since 00:00:00 ,  January 1,
                 1970 ).

       Errors:    None

     See also:    GetEpochTime (199), EpochToLocal (180), GetTime (202),GetDate (196)


                 Listing:  linuxex/ex4.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example4      ;


                 {  Program       to    d e m o n s t r a t et h e L o c a l T o E p o c hf u n c t i o n.  }


                 Uses     l i n u x;


                 Var    y e a r,month    , day  , h o u r, m i n u t e,s e c o n d :  Word    ;


                 b e g i n
                    Write     (  'Year    |_||_||_||_|:)|_|';r e a d(lYnear ) ;
                    Write     (  'Month    |_||_||_|: |_|')r;e a d l(nMonth   ) ;
                    Write     (  'Day   |_||_||_||_||_|:)|_|';r e a(dDlany) ;
                    Write     (  'Hour    |_||_||_||_|:)|_|';r e a d(lHnour ) ;
                    Write     (  'Minute     |_||_|: |_|')r;e a d l(nMinute     ) ;
                    Write     (  'Seonds     |_||_|: |_|')r;e a d l(nSecond     ) ;
                    Write     (  'T h i s|_|i s|_|: |_|') ;
                    Write     ( L o c a l T o E p o c(hy e a r, month    ,day   ,h o u r, m i n u t e,s e c o n d) ) ;
                    W r i t e l n ( ' |_|s e c o n d|s_|p a s|t_|0 0 : 0 0 |_|1 / 1 / 1 9)8;0 '
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.81         MkFifo

Declaration:      Function  MkFifo  (PathName:    String;  Mode  :    Longint)  :    Boolean;

Description:      MkFifo  creates  named  a  named  pipe  in  the  filesystem,  with  name  PathName  and  mode
                 Mode.

       Errors:    LinuxError is used to report errors:

                 sys___emfile    Too many file descriptors for this process.

                 sys___enfile   The system file table is full.

     See also:    POpen (216), MkFifo (211), mkfifo (4)
                 11.3.82         MMap

Declaration:      Function  MMap(const  m:tmmapargs):longint;

Description:      MMap maps or unmaps files or devices into memory.  The different fields of the argument m
                 determine what and how the mmap maps this:

                 address    Address where to mmap the device.  This address is a hint, and may not be followed.

                 size Size (in bytes) of area to be mapped.

                 prot  Protection of mapped memory.  This is a OR-ed combination of the following constants:

                       PROT___EXEC            The memory can be executed.

                       PROT___READ             The memory can be read.



                                                                                 211

            __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES_____________*
 *_______________
                  PROT___WRITE              The memory can be written.

                  PROT___NONE             The memory can not be accessed.

            flags  Contains some options for the mmap call.  It is an OR-ed combination of the following
                  constants:

                  MAP___FIXED            Do not map at another address than the given address.  If the address
                        cannot be used, MMap will fail.

                  MAP___SHARED               Share this map with other processes that map this object.

                  MAP___PRIVATE               Create a private map with copy-on-write semantics.

                  MAP___ANONYMOUS                     fd does not have to be a file descriptor.

                  One of the options MAP__ SHARED and MAP__ PRIVATE must be present,  but not both at
                  the same time.

            fd File descriptor from which to map.

            offset  Offset to be used in file descriptor fd.

            The function returns a pointer to the mapped memory, or a -1 in case of en error.

  Errors:    On error, -1 is returned and LinuxError is set to the error code:

            Sys___EBADF         fd is not a valid file descriptor and MAP__ ANONYMOUS was not specified.

            Sys___EACCES          MAP__ PRIVATE was specified, but fd is not open for reading.  Or MAP__ SHARED
                  was asked and PROT__ WRITE is set, fd is not open for writing

            Sys___EINVAL         One of the record fields Start, length or offset is invalid.

            Sys___ETXTBUSY              MAP__ DENYWRITE was set but the object specified by fd is open for writ-
                  ing.

            Sys___EAGAIN          fd is locked, or too much memory is locked.

            Sys___ENOMEM             Not enough memory for this operation.

See also:    MUnMap (213), mmap (2)


            Listing:  linuxex/ex66.pp

           ________________________________________________________________________________________________________________________*
 *________
            Program       Example66      ;


            {  Program       to    d e m o n s t r a t et h e MMap     f u n c t i o n.  }


            Uses     l i n u x;


            Var    S  :   S t r i n g;
                   f d, Len    :   L o n g i n t;
                   a r g s :   tmmapargs       ;
                  P   :   PChar   ;


            b e g i n
               S :=  'T h i s|_|i s|_|a|_|s t r i n'g#0;
               Len  :=  Length    ( S ) ;
               f d := fdOpen     ('  t e s t f i l.et x t' ,Open __wrOnly        or    o p e n __c r e a)t;
               I f   f d=-1    then
                   Halt   ( 1 ) ;
               I f   f d W r i t e(f d,S  [ 1 ] ,Len )=-1     then
                   Halt   ( 2 ) ;
               f d C l o s e(f d ) ;
               fdOpen     ( ' t e s t f i l.et x t' , Open __rdOnly      ) ;
               i f   f d=-1    then



                                                                            212

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                        Halt   ( 3 ) ;
                    a r g s. a d d r e s s: = 0 ;
                    a r g s. o f f s e t: = 0 ;
                    a r g s. s i z e:= Len   +1;
                    a r g s. f d:=  Fd ;
                    a r g s. f l a g s:= MAP__PRIVATE       ;
                    a r g s. p r o t:= PROT__READ        or   PROT__WRITE       ;
                    P := Pchar    ( mmap   ( a r g s) ) ;
                    I f   l o n g i n t(P)=-1     then
                        Halt   ( 4 ) ;
                    W r i t e l n(' Read   |_|i n|_|memory   |_||_|:,'P) ;
                    f d c l o s e(f d ) ;
                    i f  Not    MUnMap     (P , Len  )   Then
                        Halt   ( L i n u x E r r o)r;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.83         MUnMap

Declaration:      function  MUnMap  (P  :  Pointer;  Size  :    Longint)  :    Boolean;

Description:      MUnMap  unmaps  the  memory  block  of  size  Size,  pointed  to  by  P,  which  was  previously
                 allocated with MMap (211).

                 The function returns True if successful, False otherwise.

       Errors:    In case of error the function returns False and LinuxError is set to an error value.  See
                 MMap (211) for possible error values.

     See also:    MMap (211), munmap (2)


                 For an example, see MMap (211).
                 11.3.84         Nice

Declaration:      Procedure  Nice  (  N  :  Integer);

Description:      Nice adds -N to the priority of the running process.  The lower the priority numerically, the
                 less the process is favored.  Only the superuser can specify a negative N, i.e.  increase the rate
                 at which the process is run.

       Errors:    Errors are returned in LinuxError

                 sys___eperm      A non-superuser tried to specify a negative N, i.e.  do a priority increase.

     See also:    GetPriority (202), SetPriority (221), Nice (2)


                 Listing:  linuxex/ex15.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example15      ;


                 {  Program       to    d e m o n s t r a t et h e N i c e  and    Get  / S e t P r i o r i t yf u n c t i o n s.  }


                 Uses     l i n u x;


                 b e g i n
                    w r i t e l n ( ' S e t t i n g|_|p r i o r i t|y_|to|_|5)';
                     s e t p r i o r i t y(p r i o __p r o c e s,sg e t p i d, 5 ) ;



                                                                                 213

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    w r i t e l n ( 'New   |_|p r i o r i t|y_|= |_|',g e t p r i o r i t(yp r i o __p r o c e s,sg e t p i)d) ;
                    w r i t e l n ( ' Doing   |_|n i c e|_|1 0)';
                    n i c e  ( 1 0 ) ;
                    w r i t e l n ( 'New   |_|P r i o r i t|y_|= |_|',g e t p r i o r i t(yp r i o __p r o c e s,sg e t p i)d) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.85         Octal

Declaration:      Function  Octal(l:longint):longint;

Description:      Octal will convert a number specified as an octal number to it's decimal value.

                 This is useful for the Chmod (175) call, where permissions are specified as octal numbers.

       Errors:    No checking is performed whether the given number is a correct Octal number.  e.g.  speci-
                 fying 998 is possible; the result will be wrong in that case.

     See also:    Chmod (175).


                 Listing:  linuxex/ex68.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example68      ;


                 {  Program       to    d e m o n s t r a t et h e O c t a l  f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n(' Mode   |_|7 7 7 |_|: |_|',O c t a(l7 7 7 ) ) ;
                    W r i t e l n(' Mode   |_|6 4 4 |_|: |_|',O c t a(l6 4 4 ) ) ;
                    W r i t e l n(' Mode   |_|7 5 5 |_|: |_|',O c t a(l7 5 5 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.86         OpenDir

Declaration:      Function  OpenDir  (f:pchar)  :    pdir;  Function  OpenDir  (f:string)  :    pdir;

Description:      OpenDir opens the directory f, and returns a pdir pointer to a Dir record, which can be
                 used to read the directory structure.  If the directory cannot be opened, nil is returned.

       Errors:    Errors are returned in LinuxError.

     See also:    CloseDir (177), ReadDir (217), SeekDir (219), TellDir (231), opendir (3)


                 Listing:  linuxex/ex35.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example35      ;


                 {  Program       to    d e m o n s t r a t et h e
                    OpenDir      ,R e a d D i r,  S e e k D i r and    T e l l D i r f u n c t i o n s.  }


                 Uses     l i n u x;


                 Var    TheDir      :  PDir   ;
                        A D i r e n t :  P D i r e n t;
                        E n t r y :   L o n g i n t;
                                                                                 214

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 b e g i n
                    TheDir     := OpenDir     ( ' . / . ') ;
                    Repeat
                        E n t r y:= T e l l D i r(TheDir    ) ;
                        A D i r e n t:=R e a d D i r ( TheDir     ) ;
                        I f  A D i r e n t<> N i l  then
                           With     A D i r e n t^ do
                               b e g i n
                               W r i t e l n( ' E n t r y|_|No|_|: |_|',E n t r y) ;
                               W r i t e l n( ' I n o d e|_||_||_||_|:,|_|'i)n;o
                               W r i t e l n( ' O f f s e t|_||_||_|:,|_|'o f)f;
                               W r i t e l n( ' R e c l e n|_||_||_|:,|_|'r e c l)e;n
                               W r i t e l n( ' Name    |_||_||_||_||_|:,|_|'p c(h@anrame [ 0 ] ) ) ;
                               end  ;
                    U n t i l  A D i r e n t=N i l;
                    Repeat
                        Write     ( ' E n t r y|_|No. |_|you|_|would   |_|l i k e|_|to|_|s e|e_|a g a i|n_|(-1 |_|to|_|s t o)p: |_|*
 *') ;
                        ReadLn      ( E n t r y) ;
                        I f  E n t r y<>-1    then
                           b e g i n
                           S e e k D i r ( TheDir    , E n t r y) ;
                           A D i r e n t:= R e a d D i r ( TheDir    ) ;
                           I f   A D i r e n<t> N i l  then
                               With    A D i r e n t^  do
                                  b e g i n
                                  W r i t e l n ( ' E n t r y|_|No|_|: |_|',E n t r)y;
                                  W r i t e l n ( ' I n o d e|_||_||_||_|:,|_|'i)n;o
                                  W r i t e l n ( ' O f f s e t|_||_||_|:,|_|'o f)f;
                                  W r i t e l n ( ' R e c l e n|_||_||_|:,|_|'r e c l)e;n
                                  W r i t e l n ( 'Name    |_||_||_||_||_|:,|_|'p c(h@anrame  [ 0 ] ) ) ;
                                  end  ;
                        end  ;
                    U n t i l  E n t r y=-1;
                    C l o s e D i r ( TheDir    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.87         pause

Declaration:      Procedure  Pause;

Description:      Pause puts the process to sleep and waits until the application receives a signal.  If a signal
                 handler is installed for the received sigal, the handler will be called and after that pause will
                 return control to the process.

       Errors:    None.


                 For an example, see Alarm (170).
                 11.3.88         PClose

Declaration:      Function  PClose  (Var  F  :  FileType)  :    longint;

Description:      PClose closes a file opened with POpen.  It waits for the command to complete, and then
                 returns the exit status of the command.

       Errors:    LinuxError is used to report errors.  If it is different from zero, the exit status is not valid.
                                                                                 215

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
     See also:    POpen (216)


                 For an example, see POpen (216)
                 11.3.89         POpen

Declaration:      Procedure  POpen  (Var  F  :  FileType;  Cmd  :    pathstr;  rw  :    char);

Description:      Popen runs the command specified in Cmd, and redirects the standard in or output of the
                 command to the other end of the pipe F. The parameter rw indicates the direction of the
                 pipe.  If it is set to 'W', then F can be used to write data, which will then be read by the
                 command from stdinput.  If it is set to 'R', then the standard output of the command can
                 be read from F. F should be reset or rewritten prior to using it.  F can be of type Text or
                 File.  A file opened with POpen can be closed with Close, but also with PClose (215).  The
                 result is the same, but PClose returns the exit status of the command Cmd.

       Errors:    Errors  are  reported  in  LinuxError  and  are  essentially  those  of  the  Execve,  Dup  and  As-
                 signPipe commands.

     See also:    AssignPipe (171), popen (3) , PClose (215)


                 Listing:  linuxex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example37      ;


                 {  Program       to    d e m o n s t r a t et h e Popen      f u n c t i o n.  }


                 u s e s  l i n u x;


                 v a r  f  :   t e x t;
                        i  :   l o n g i n t;


                 b e g i n
                    w r i t e l n ( ' C r e a t i n g|_|a|_|s h e l|l_|s c r i|p_t|to|_|which |_|e c h o e|s_|i t|s_|a r g u m e n'*
 *t)s;
                    w r i t e l n ( ' and  |_|i n p u|t_|back |_|to|_|s t d o u t') ;
                    a s s i g n ( f , ' t e s t 2 1 a') ;
                    r e w r i t e ( f ) ;
                    w r i t e l n ( f ,'#!/   b i n/ sh  ' ) ;
                    w r i t e l n ( f ,' echo   |_|t h i s|_|i|s_|t h|e_|c h i l|d_|s p e a k i n.g. . . |_|') ;
                    w r i t e l n ( f ,' echo   |_|g o t|_|a r g u m e n t|s_|\*"$* " \ * ') ;
                    w r i t e l n ( f ,' c a t' ) ;
                    w r i t e l n ( f ,' e x i t|_|2 ') ;
                    w r i t e l n ( f ) ;
                    c l o s e (  f) ;
                    chmod     (  't e s t 2 1 a', o c t a l ( 7 5 5 ) ) ;
                    popen     (  f, ' . /t e s t 2 1 a|_|a r g|1_|a r g'2,'W  ' ) ;
                    i f   l i n u x e r r o<r>0   then
                          w r i t e l n( ' e r r o r|_|from |_|POpen   |_|: |_|L i n u x e r r|o_r|: |_|',L i n u x e r r)o;r
                    f o r  i :=1    to   1 0  do
                        w r i t e l n( f , ' T h i s|_|i s|_|w r i t t e|n_|to|_|t h|e_|p i p,e|_|and|_|s h o u l|d_|a p p e a|r_|o*
 *n|_|s t d o.u't) ;
                    F l u s h( f ) ;
                    W r i t e l n ( ' The  |_|s c r i p|t_|e x i t e|d_|w i t|h_|s t a t u|s_|:,|_|'P C l o s(ef ) ) ;
                    w r i t e l n;
                    w r i t e l n ( ' P r e s s|_|<r e t u r>n|_|to|_|remove    |_|s h e l|l_|s c r i p.t') ;
                    r e a d l n;
                    a s s i g n ( f , ' t e s t 2 1 a') ;
                    e r a s e (  f)
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 216

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.90         ReadDir

Declaration:      Function  ReadDir  (p:pdir)  :    pdirent;

Description:      ReadDir reads the next entry in the directory pointed to by p.  It returns a pdirent pointer
                 to a structure describing the entry.  If the next entry can't be read, Nil is returned.

       Errors:    Errors are returned in LinuxError.

     See also:    CloseDir (177), OpenDir (214), SeekDir (219), TellDir (231), readdir (3)


                 For an example, see OpenDir (214).
                 11.3.91         ReadLink

Declaration:      Function  ReadLink(name,linkname:pchar;maxlen:longint):longint;  Function  ReadLink(name:pathstr):pathstr;

Description:      ReadLink  returns  the  file  the  symbolic  link  name  is  pointing  to.   The  first  form  of  this
                 function accepts a buffer linkname of length maxlen where the filename will be stored.  It
                 returns the actual number of characters stored in the buffer.

                 The second form of the function returns simply the name of the file.

       Errors:    On error, the first form of the function returns -1; the second one returns an empty string.
                 LinuxError is set to report errors:

                 SYS___ENOTDIR             A part of the path in Name is not a directory.

                 SYS___EINVAL           maxlen is not positive, or the file is not a symbolic link.

                 SYS___ENAMETOOLONG                       A pathname, or a component of a pathname, was too long.

                 SYS___ENOENT            the link name does not exist.

                 SYS___EACCES           No permission to search a directory in the path

                 SYS___ELOOP          Too many symbolic links were encountered in trans lating the pathname.

                 SYS___EIO      An I/O error occurred while reading from the file system.

                 SYS___EFAULT           The buffer is not part of the the process's memory space.

                 SYS___ENOMEM              Not enough kernel memory was available.

     See also:    SymLink (226)


                 Listing:  linuxex/ex62.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example62      ;


                 {  Program       to    d e m o n s t r a t et h e R e a d L i n k f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    F  :   Text   ;
                        S  :   S t r i n g;


                 b e g i n
                    A s s i g n ( F , ' t e s t.t x t' ) ;
                    R e w r i t e ( F ) ;
                    W r i t e l n ( F ,' T h i s|_|i s|_|w r i t t e|n_|to|_|t e s.tt x t') ;
                    C l o s e( f ) ;
                    {   new  . t x t  and    t e s t.t x t  a r e  now    t h e  same     f i l e }



                                                                                 217

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    i f  not    SymLink       ( ' t e s t. t x t' ,' new  . t x t' )  then
                        w r i t e l n( ' E r r o r|_|when  |_|s y m l i n k i n|g_|!)';
                    S :=  R e a d L i n(k' new  . t x t' ) ;
                    I f  S = ' '  then
                        W r i t e l n( ' E r r o r|_|r e a d i n|g_|l i n|k_|!)'
                    E l s e
                        W r i t e l n( ' L i n k|_|p o i n t|s_|to|_|: |_|',S) ;
                   {  Now    remove      l i n k s }
                   I f  not    U n l i n k ( 'new   .t x t ')   then
                      W r i t e l n ( ' E r r o r|_|when |_|u n l i n k i n|g_|!)';
                   I f  not    U n l i n k ( ' t e s t.t x t' )   then
                      W r i t e l n ( ' E r r o r|_|when |_|u n l i n k i n|g_|!)';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.92         ReadPort

Declaration:      Procedure  ReadPort  (Port  :    Longint;  Var  Value  :    Byte);  Procedure  ReadPort  (Port
                 :    Longint;  Var  Value  :    Word);  Procedure  ReadPort  (Port  :    Longint;  Var  Value
                 :    Longint);

Description:      ReadPort reads one Byte, Word or Longint from port Port into Value.

                 Note that you need permission to read a port.  This permission can be set by the root user
                 with the IOperm (205) call.

       Errors:    In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                 will occur.

     See also:    IOperm (205), ReadPortB (218), ReadPortW (219), ReadPortL (218),WritePort (234), WritePortB
                 (234), WritePortL (235), WritePortW (235)
                 11.3.93         ReadPortB

Declaration:      Procedure  ReadPortB  (Port  :    Longint;  Var  Buf;  Count:    longint);  Function  ReadPortB
                 (Port  :    Longint):    Byte;

Description:      The procedural form of  ReadPortB reads Count bytes from port Port and stores them in
                 Buf.  There must be enough memory allocated at Buf to store Count bytes.

                 The functional form of  ReadPortB reads 1 byte from port B and returns the byte that was
                 read.

                 Note that you need permission to read a port.  This permission can be set by the root user
                 with the IOperm (205) call.

       Errors:    In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                 will occur.

     See also:    IOperm (205), ReadPort (218), ReadPortW (219), ReadPortL (218),WritePort (234), WritePortB
                 (234), WritePortL (235), WritePortW (235)
                 11.3.94         ReadPortL

Declaration:      function  ReadPortL  (Port  :    Longint):    LongInt;  Procedure  ReadPortL  (Port  :    Longint;
                 Var  Buf;  Count:    longint);



                                                                                 218

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      The procedural form of  ReadPortL reads Count longints from port Port and stores them
                 in Buf.  There must be enough memory allocated at Buf to store Count Longints.

                 The functional form of  ReadPortB reads 1 longint from port B and returns the longint that
                 was read.

                 Note that you need permission to read a port.  This permission can be set by the root user
                 with the IOperm (205) call.

       Errors:    In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                 will occur.

     See also:    IOperm (205), ReadPort (218), ReadPortW (219), ReadPortB (218),WritePort (234), WritePortB
                 (234), WritePortL (235), WritePortW (235)
                 11.3.95         ReadPortW

Declaration:      Procedure  ReadPortW  (Port  :    Longint;  Var  Buf;  Count:    longint);  function  ReadPortW
                 (Port  :    Longint):    Word;

Description:      The procedural form of  ReadPortB reads Count words from port Port and stores them in
                 Buf.  There must be enough memory allocated at Buf to store Count words.

                 The functional form of  ReadPortB reads 1 word from port B and returns the word that was
                 read.

                 Note that you need permission to read a port.  This permission can be set by the root user
                 with the IOperm (205) call.

       Errors:    In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                 will occur.

     See also:    IOperm (205), ReadPort (218), ReadPortB (218), ReadPortL (218),WritePort (234), WritePortB
                 (234), WritePortL (235), WritePortW (235)
                 11.3.96         ReadTimezoneFile

Declaration:      procedure  ReadTimezoneFile(fn:string);

Description:      ReadTimeZoneFile reads the timezone file fn and initializes the local time routines based
                 on the information found there.

                 There should be no need to call this function.  The initialization routines of the linux unit
                 call this routine at unit startup.

       Errors:    None.

     See also:    GetTimezoneFile (203), GetLocalTimezone (201)
                 11.3.97         SeekDir

Declaration:      Procedure  SeekDir  (p:pdir;off:longint);

Description:      SeekDir sets the directory pointer to the off-th entry in the directory structure pointed
                 to by p.

       Errors:    Errors are returned in LinuxError.

     See also:    CloseDir (177), ReadDir (217), OpenDir (214), TellDir (231), seekdir (3)


                 For an example, see OpenDir (214).



                                                                                 219

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.98         Select

Declaration:      Function  Select  (N  :  Longint;
                 var  readfds,writefds,exceptfds  :    PFDset;  Var  Timeout)  :    Longint;

Description:      Select checks one of the file descriptors in the FDSets to see if its status changed.  readfds,
                 writefds and exceptfds are pointers to arrays of 256 bits.  If you want a file descriptor to
                 be checked, you set the corresponding element in the array to 1.  The other elements in the
                 array must be set to zero.  Three arrays are passed :  The entries in readfds are checked to
                 see if characters become available for reading.  The entries in writefds are checked to see
                 if it is OK to write to them,  while entries in exceptfds are cheked to see if an exception
                 occorred on them.  You can use the functions FD__ ZERO (185), FD__ Clr (186), FD__ Set (186),
                 FD__ IsSet (186) to manipulate the individual elements of a set.  The pointers can be nil.  N is
                 the largest index of a nonzero entry plus 1.  (= the largest file-descriptor + 1).  TimeOut can
                 be used to set a time limit.  If  TimeOut can be two types :

                     1.TimeOut  is  of  type  PTime  and  contains  a  zero  time,  the  call  returns  immediately.  If
                       TimeOut is Nil, the kernel will wait forever, or until a status changed.

                     2.TimeOut is of type Longint.  If it is -1, this has the same effect as a Timeout of type
                       PTime which is Nil.  Otherwise, TimeOut contains a time in milliseconds.

                 When the TimeOut is reached,  or one of the file descriptors has changed,  the Select call
                 returns.  On return, it will have modified the entries in the array which have actually changed,
                 and it returns the number of entries that have been changed.  If the timout was reached, and
                 no decsriptor changed, zero is returned; The arrays of indexes are undefined after that.  On
                 error, -1 is returned.

       Errors:    On error, the function returns -1, and Errors are reported in LinuxError :

                 SYS___EBADF            An invalid descriptot was specified in one of the sets.

                 SYS___EINTR           A non blocked signal was caught.

                 SYS___EINVAL            N is negative or too big.

                 SYS___ENOMEM               Select was unable to allocate memory for its internal tables.

     See also:    SelectText  (221),  GetFS  (199),  FD__ ZERO  (185),  FD__ Clr  (186),  FD__ Set  (186),  FD__ IsSet
                 (186)


                 Listing:  linuxex/ex33.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example33      ;


                 {  Program       to    d e m o n s t r a t et h e S e l e c t  f u n c t i o n.  }


                 Uses     l i n u x;


                 Var   FDS     :  FDSet    ;


                 b e g i n
                    FD __Zero     ( FDS  ) ;
                    FD __Set    ( 0 ,FDS   ) ;
                    W r i t e l n ( ' P r e s s|_|t h|e_|<ENTER  >|_|to  |_|c o n t i n u|e_|t h|e_|program  . ' ) ;
                    {   Wait     u n t i l F i l e  d e s c r i p t o r0  ( = I n p u t)  c h a n g e s}
                    S e l e c t ( 1 ,@FDS    , n i l, n i l, n i l) ;
                    {   Get    r i d  o f < ENTER    >   i n  b u f f e r }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s|_|<ENTER  >|_|key  |_|i n|_|l e s|s_|t h a|n_|2s|_|e c o n d.s. . ') ;



                                                                                 220

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    FD __Zero     ( FDS  ) ;
                    FD __Set    ( 0 ,FDS   ) ;
                    i f   S e l e c t ( 1 ,@FDS   , n i l, n i l, 2 0 0 0 ) > 0then
                        W r i t e l n( ' Thank    |_|you |_|! ')
                        {  FD__ISSET     ( 0 ,FDS   )  would      be   t r u e  h e r e.  }
                    e l s e
                        W r i t e l n( ' Too  |_|l a t e|_|!)';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.99         SelectText

Declaration:      Function  SelectText  (  var  T  :  Text;  TimeOut  :PTime)  :    Longint;

Description:      SelectText executes the Select (220) call on a file of type Text.  You can specify a timeout
                 in TimeOut.  The SelectText call determines itself whether it should check for read or write,
                 depending on how the file was opened :  With Reset it is checked for reading, with Rewrite
                 and Append it is checked for writing.

       Errors:    See Select (220).  SYS__ EBADF can also mean that the file wasn't opened.

     See also:    Select (220), GetFS (199)
                 11.3.100          SetPriority

Declaration:      Function  SetPriority  (Which,Who,Prio  :    Integer)  :    Integer;

Description:      SetPriority sets the priority with which a process is running.  Which process(es) is deter-
                 mined by the Which and Who variables.  Which can be one of the pre-defined Prio__ Process,
                 Prio__ PGrp,  Prio__ User, in which case Who is the process ID, Process group ID or User ID,
                 respectively.  Prio is a value in the range -20 to 20.

       Errors:    Error checking must be done on LinuxError, since a priority can be negative.

                 sys___esrch    No process found using which and who.

                 sys___einval    Which was not one of  Prio__ Process,  Prio__ Grp  or  Prio__ User.

                 sys___eperm      A process was found, but neither its effective or real user ID match the effective
                       user ID of the caller.

                 sys___eacces     A non-superuser tried to a priority increase.

     See also:    GetPriority (202), Nice (213), Setpriority (2)


                 For an example, see Nice (213).
                 11.3.101          Shell

Declaration:      Function  Shell  (Command  :    String)  :    Longint;

Description:      Shell invokes the bash shell (/bin/sh), and feeds it the command Command (using the -c
                 option).  The function then waits for the command to complete, and then returns the exit
                 status of the command, or 127 if it could not complete the Fork (195) or Execve (184) calls.

       Errors:    Errors are reported in LinuxError.

     See also:    POpen (216), Fork (195), Execve (184), system (3)

                                                                                 221

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Listing:  linuxex/ex56.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       e x a m p l e 5;6


                 u s e s  l i n u x;


                 {  Program       to    d e m o n s t r a t et h e S h e l l  f u n c t i o n}


                 Var    S  :   L o n g i n t;


                 b e g i n
                    W r i t e l n ( ' Output    |_|o f|_|l s|_|-l|_|*p.p ') ;
                    S :=  S h e l l ( ' l s|_|-l|_|* .pp ' ) ;
                    W r i t e l n ( 'Command      |_|e x i t e|d_|wwith  |_|s t a t u|s_|: |_|',S) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.102          SigAction

Declaration:      Procedure  SigAction  (Signum  :    Integer;  Var  Act,OldAct  :    PSigActionRec);

Description:      Changes  the  action  to  take  upon  receipt  of  a  signal.   Act  and  Oldact  are  pointers  to  a
                 SigActionRec record.  SigNum specifies the signal, and can be any signal except SIGKILL
                 or  SIGSTOP.  If  Act  is  non-nil,  then  the  new  action  for  signal  SigNum  is  taken  from  it.
                 If  OldAct is non-nil,  the old action is stored there.  Sa__ Handler may be SIG__ DFL for the
                 default action or SIG__ IGN to ignore the signal.  Sa__ Mask Specifies which signals should be
                 ignord during the execution of the signal handler.  Sa__ Flags Speciefies a series of flags which
                 modify the behaviour of the signal handler.  You can 'or' none or more of the following :

                 SA___NOCLDSTOP                If  signum  is  SIGCHLD  do  not  receive  notification  when  child  pro-
                       cesses stop.

                 SA___ONESHOT or SA___RESETHAND                               Restore  the  signal  action  to  the  default  state
                       once the signal handler has been called.

                 SA___RESTART            For compatibility with BSD signals.

                 SA___NOMASK or SA___NODEFER                           Do not prevent the signal from being received from
                       within its own signal handler.

       Errors:    LinuxError is used to report errors.

                 sys___einval    an invalid signal was specified, or it was SIGKILL or SIGSTOP.

                 sys___efault    Act,OldAct point outside this process address space

                 sys___eintr   System call was interrupted.

     See also:    SigProcMask (223), SigPending (223), SigSuspend (224), Kill (208), Sigaction (2)


                 Listing:  linuxex/ex57.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       e x a m p l e 5;7


                 {  Program       to    d e m o n s t r a t et h e S i g A c t i o n f u n c t i o n. }


                 {
                 do   a   k i l l-  USR1     p i d  from    a n o t h e r t e r m i n a l to   s e e  what     h a p p e n s.
                 r e p l a c e p i d  w i t h t h e   r e a l p i d  o f  t h i s  program     .
                 You    can    g e t  t h i s p i d  by    r u n n i n g 'ps  ' .
                                                                                 222

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 }


                 u s e s  L i n u x;


                 Var
                      oa  ,na   :   P S i g A c t i o n R e;c


                 Procedure        DoSig    ( s i g  :  L o n g i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n|g_|s i g n a:l|_|',s i g) ;
                 end  ;


                 b e g i n
                      new  ( na  ) ;
                      new  ( oa  ) ;
                      na  ^ .H a n d l e r.sh :=  @DoSig    ;
                      na  ^ .Sa__Mask    : = 0 ;
                      na  ^ .S a __F l a g s: = 0 ;
                      na  ^ .S a __R e s t o r e:r= N i l;
                      S i g A c t i o n(S i g U s r 1,na , oa ) ;
                      i f  L i n u x E r r o<r>0    then
                          b e g i n
                          w r i t e l n('E r r o r: |_|',l i n u x e r r o,r' . ') ;
                          h a l t( 1 ) ;
                         end   ;
                      W r i t e l n ( 'Send   |_|USR1  |_|s i g n a|l_|o r|_|p r e s|s_|<ENTER >|_|to |_|e x i t') ;
                      r e a d l n;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.103          SigPending

Declaration:      Function  SigPending  :    SigSet;

Description:      Sigpending allows the examination of pending signals (which have been raised while blocked.)
                 The signal mask of pending signals is returned.

       Errors:    None

     See also:    SigAction (222), SigProcMask (223), SigSuspend (224), Signal (225), Kill (208), Sigpending
                 (2)
                 11.3.104          SigProcMask

Declaration:      Procedure  SigProcMask  (How  :    Integer;  SSet,OldSSet  :    PSigSet);

Description:      Changes the list of currently blocked signals.  The behaviour of the call depends on How :

                 SIG___BLOCK          The set of blocked signals is the union of the current set and the SSet argu-
                       ment.

                 SIG___UNBLOCK              The signals in SSet are removed from the set of currently blocked signals.

                 SIG___SETMASK             The list of blocked signals is set so SSet.

                 If  OldSSet is non-nil, then the old set is stored in it.

       Errors:    LinuxError is used to report errors.
                                                                                 223

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___efault    SSet or OldSSet point to an adress outside the range of the process.

                 sys___eintr   System call was interrupted.

     See also:    SigAction (222), SigPending (223), SigSuspend (224), Kill (208), Sigprocmask (2)
                 11.3.105          SigRaise

Declaration:      Procedure  SigRaise(Sig:integer);

Description:      SigRaise sends a Sig signal to the current process.

       Errors:    None.

     See also:    Kill (208), GetPid (201)


                 Listing:  linuxex/ex65.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       e x a m p l e 6;4


                 {  Program       to    d e m o n s t r a t et h e S i g R a i s e f u n c t i o n. }


                 u s e s  L i n u x;


                 Var
                      oa  ,na   :   P S i g A c t i o n R e;c


                 Procedure        DoSig    ( s i g  :  L o n g i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n|g_|s i g n a:l|_|',s i g) ;
                 end  ;


                 b e g i n
                      new  ( na  ) ;
                      new  ( oa  ) ;
                      na  ^ .h a n d l e r.sh :=  @DoSig    ;
                      na  ^ .Sa__Mask    : = 0 ;
                      na  ^ .S a __F l a g s: = 0 ;
                      na  ^ .S a __R e s t o r e:r= N i l;
                      S i g A c t i o n(S i g U s r 1,na , oa ) ;
                      i f  L i n u x E r r o<r>0    then
                          b e g i n
                          w r i t e l n('E r r o r: |_|',l i n u x e r r o,r' . ') ;
                          h a l t( 1 ) ;
                         end   ;
                      W r i t e l n(' S e n d i n g|_|USR1 |_|( ',s i g u s r 1,' ) |_|s i g n a|l_|to|_|s e l.f') ;
                      S i g R a i s e(s i g u s r 1) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.106          SigSuspend

Declaration:      Procedure  SigSuspend  (Mask  :    SigSet);

Description:      SigSuspend temporarily replaces the signal mask for the process with the one given in Mask,
                 and then suspends the process until a signal is received.

       Errors:    None



                                                                                 224

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
     See also:    SigAction (222), SigProcMask (223), SigPending (223), Signal (225), Kill (208), SigSuspend
                 (2)
                 11.3.107          Signal

Declaration:      Function  Signal  (SigNum  :    Integer;  Handler  :    SignalHandler)  :    SignalHandler;

Description:      Signal installs a new signal handler for signal SigNum.  This call has the same functionality
                 as the SigAction call.  The return value for Signal is the old signal handler, or nil on error.

       Errors:    LinuxError is used to report errors :

                 SIG___ERR       An error occurred.

     See also:    SigAction (222),Kill (208), Signal (2)


                 Listing:  linuxex/ex58.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       e x a m p l e 5;8


                 {  Program       to    d e m o n s t r a t et h e S i g n a l  f u n c t i o n. }


                 {
                 do   a   k i l l-  USR1     p i d  from    a n o t h e r t e r m i n a l to   s e e  what     h a p p e n s.
                 r e p l a c e p i d  w i t h t h e   r e a l p i d  o f  t h i s  program     .
                 You    can    g e t  t h i s p i d  by    r u n n i n g 'ps  ' .
                 }


                 u s e s  L i n u x;


                 Procedure        DoSig    ( s i g  :  L o n g i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n|g_|s i g n a:l|_|',s i g) ;
                 end  ;


                 b e g i n
                      S i g N a l(S i g U s r 1,@DoSig     ) ;
                      i f  L i n u x E r r o<r>0    then
                          b e g i n
                          w r i t e l n('E r r o r: |_|',l i n u x e r r o,r' . ') ;
                          h a l t( 1 ) ;
                         end   ;
                      W r i t e l n ( 'Send   |_|USR1  |_|s i g n a|l_|o r|_|p r e s|s_|<ENTER >|_|to |_|e x i t') ;
                      r e a d l n;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.108          StringToPPchar

Declaration:      Function  StringToPPChar(Var  S:STring):ppchar;

Description:      StringToPPChar splits the string S in words, replacing any whitespace with zero characters.
                 It returns a pointer to an array of pchars that point to the first letters of the words in S.
                 This array is terminated by a Nil pointer.

                 The function does not add a zero character to the end of the string unless it ends on whites-
                 pace.



                                                                                 225

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 The function reserves memory on the heap to store the array of PChar; The caller is respon-
                 sible for freeing this memory.

                 This function can be called to create arguments for the various Exec calls.

       Errors:    None.

     See also:    CreateShellArgV (177), Execve (184), Execv (183)


                 Listing:  linuxex/ex70.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example70      ;


                 {  Program       to    d e m o n s t r a t et h e S t r i n g T o P P c h a rf u n c t i o n.  }


                 Uses     l i n u x;


                 Var    S  :   S t r i n g;
                       P   :   PPChar    ;
                        I  :   l o n g i n t;


                 b e g i n
                    / /   r e m a r k w h i t e s p a c eat   end  .
                    S :=  'T h i s|_|i s|_|a|_|s t r i n|g_|w i t|h_|words . |_|';
                    P :=  S t r i n g T o P P C h a(rS) ;
                    I : = 0 ;
                    While     P  [i ]<>  N i l  do
                        b e g i n
                        W r i t e l n('Word    |_|',i, ' |_|: |_|',P[i ] ) ;
                        I n c( I ) ;
                        end  ;
                    FreeMem     ( P , i* S i z e O f(Pchar    ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.109          SymLink

Declaration:      Function  SymLink  (OldPath,NewPath  :    pathstr)  :    Boolean;

Description:      SymLink makes Newpath point to the file in OldPath, which doesn't necessarily exist.  The
                 two files DO NOT have the same inode number.  This is known as a 'soft' link.  The permis-
                 sions of the link are irrelevant, as they are not used when following the link.  Ownership of
                 the file is only checked in case of removal or renaming of the link.  The function returns True
                 if the call was succesfull, False if the call failed.

       Errors:    Errors are returned in LinuxError.

                 sys___eperm      The filesystem containing oldpath and newpath doesn't support linking files.

                 sys___eaccess     Write access for the directory containing Newpath is disallowed, or one of the
                       directories in OldPath or NewPath has no search (=execute) permission.

                 sys___enoent     A directory entry in OldPath or NewPath does not exist or is a symbolic link
                       pointing to a non-existent directory.

                 sys___enotdir     A directory entry in OldPath or NewPath is nor a directory.

                 sys___enomem        Insufficient kernel memory.

                 sys___erofs   The files are on a read-only filesystem.

                 sys___eexist    NewPath already exists.



                                                                                 226

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 sys___eloop    OldPath or NewPath has a reference to a circular symbolic link, i.e.  a symbolic
                       link, whose expansion points to itself.

                 sys___enospc     The device containing NewPath has no room for anothe entry.

     See also:    Link (209), UnLink (232), ReadLink (217), Symlink (2)


                 Listing:  linuxex/ex22.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example22      ;


                 {  Program       to    d e m o n s t r a t et h e SymLink       and    UnLink       f u n c t i o n.s }


                 Uses     l i n u x;


                 Var    F  :   Text   ;
                        S  :   S t r i n g;


                 b e g i n
                    A s s i g n ( F , ' t e s t.t x t' ) ;
                    R e w r i t e ( F ) ;
                    W r i t e l n ( F ,' T h i s|_|i s|_|w r i t t e|n_|to|_|t e s.tt x t') ;
                    C l o s e( f ) ;
                    {   new  . t x t  and    t e s t.t x t  a r e  now    t h e  same     f i l e }
                    i f  not    SymLink       ( ' t e s t. t x t' ,' new  . t x t' )  then
                        w r i t e l n( ' E r r o r|_|when  |_|s y m l i n k i n|g_|!)';
                    {   Removing        t e s t.t x t   s t i l l l e a v e s new  . t x t
                        P o i n t i n gnow    to    a  non  - e x i s t e n t f i l e !  }
                    I f  not     U n l i n k( ' t e s t. t x t' )  then
                        W r i t e l n( ' E r r o r|_|when  |_|u n l i n k i n|g_|!)';
                    A s s i g n ( f , 'new   . t x t' ) ;
                    {   T h i s  s h o u l d f a i l,  s i n c e  t h e  s y m b o l i cl i n k
                        p o i n t s to   a   non -  e x i s t e n t f i l e!  }
                    { $ i-}
                    Reset     ( F ) ;
                    { $ i+}
                    I f   I O R e s u l=t0   then
                        W r i t e l n( ' T h i s|_|s h o u l d'n' t|_|happen    ') ;
                   {  Now    remove      new  . t x t  a l s o }
                   I f  not    U n l i n k ( 'new   .t x t ')   then
                      W r i t e l n ( ' E r r o r|_|when |_|u n l i n k i n|g_|!)';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.110          SysInfo

Declaration:      Function  SysInfo(var  Info:TSysinfo):Boolean;

Description:      SysInfo returns system information in Info.  Returned information in Info includes:

                 uptime     Number of seconds since boot.

                 loads   1, 5 and 15 minute load averages.

                 totalram     total amount of main memory.

                 freeram     amount of free memory.

                 sharedram       amount of shared memory

                 bufferram      amount of memory used by buffers.
                                                                                 227

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 totalswap      total amount of swapspace.

                 freeswap     amount of free swapspace.

                 procs   number of current processes.

       Errors:    None.

     See also:    Uname (232)


                 Listing:  linuxex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 program       Example64      ;


                 {  Example       to    d e m o n s t r a t et h e S y s I n f o f u n c t i o n}


                 Uses     L i n u x;


                 F u n c t i o nMb  (L   :   L o n g i n t)  :  l o n g i n t;


                 b e g i n
                    Mb  := L   d i v ( 1 0 2 4 * 1 0 2 4 ) ;
                 end  ;


                 Var    I n f o :   T S y s I n f o;
                       D  ,M , S e c s,H   :   l o n g i n t;


                 b e g i n
                    I f  Not     S y s I n f o(I n f o)  then
                        Halt   ( 1 ) ;
                    With     I n f o  do
                        b e g i n
                       D :=  Uptime      d i v  ( 3 6 0 0 * 2 4 ) ;
                        UpTime    :=  UpTime      mod    ( 3 6 0 0 * 2 4 ) ;
                        h:=  u p t i m e d i v  3 6 0 0 ;
                        u p t i m e:= u p t i m e mod    3 6 0 0 ;
                       m :=  u p t i m e d i v  6 0 ;
                        s e c s:= u p t i m e mod    6 0 ;
                        W r i t e l n('Uptime     |_|: |_|',d,' d a y s, |_|',h ,' |_|h o u r s, |_|',m,' |_|min , |_|',s e c s,' |*
 *_|s. ') ;
                        W r i t e l n('Loads     |_||_|: |_|',Loads [ 1 ] ,' / ',Loads    [ 2 ] ,' / ', Loads    [ 3 ] ) ;
                        W r i t e l n('T o t a l|_|Ram  |_||_|: |_|',Mb(t o t a l r a)m,' Mb  . ') ;
                        W r i t e l n('F r e e|_|Ram  |_||_||_|:,|_|'Mb(f r e e r a)m, 'Mb  . ') ;
                        W r i t e l n('S h a r e d|_|Ram |_|: |_|',Mb( s h a r e d r a m) ,'Mb . ' ) ;
                        W r i t e l n(' B u f f e r|_|Ram|_|: |_|',Mb( b u f f e r r a m) ,'Mb . ' ) ;
                        W r i t e l n('T o t a l|_|Swap  |_|: |_|',Mb( t o t a l s w a p) ,'Mb . ' ) ;
                        W r i t e l n('F r e e|_|Swap   |_||_|: |_|',Mb(f r e e s w a)p,' Mb  . ') ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.111          TCDrain

Declaration:      Function  TCDrain  (Fd:longint)  :    Boolean;

Description:      TCDrain waits until all data to file descriptor Fd is transmitted.

                 The function returns True if the call was succesfull, False otherwise.

       Errors:    Errors are reported in LinuxError

     See also:    termios (2)



                                                                                 228

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.112          TCFlow

Declaration:      Function  TCFlow  (Fd,Act:longint)  :    Boolean;

Description:      TCFlow suspends/resumes transmission or reception of data to or from the file descriptor
                 Fd, depending on the action Act.  This can be one of the following pre-defined values:

                 TCOOFF          suspend reception/transmission,

                 TCOON         resume reception/transmission,

                 TCIOFF        transmit a stop character to stop input from the terminal,

                 TCION        transmit start to resume input from the terminal.

                 The function returns True if the call was succesfull, False otherwise.

       Errors:    Errors are reported in LinuxError.

     See also:    termios (2)
                 11.3.113          TCFlush

Declaration:      Function  TCFlush  (Fd,QSel:longint)  :    Boolean;

Description:      TCFlush discards all data sent or received to/from file descriptor fd.  QSel indicates which
                 queue should be discard.  It can be one of the following pre-defined values :

                 TCIFLUSH           input,

                 TCOFLUSH             output,

                 TCIOFLUSH             both input and output.

                 The function returns True if the call was succesfull, False otherwise.

       Errors:    Errors are reported in LinuxError.

     See also:    termios (2)
                 11.3.114          TCGetAttr

Declaration:      Function  TCGetAttr  (fd:longint;var  tios:TermIOS)  :  Boolean;

Description:      TCGetAttr gets the terminal parameters from the terminal referred to by the file descriptor
                 fd and returns them in a TermIOS structure tios.  The function returns True if the call was
                 succesfull, False otherwise.

       Errors:    Errors are reported in LinuxError

     See also:    TCSetAttr (230), termios (2)


                 Listing:  linuxex/ex55.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example55      ;


                 u s e s  L i n u x;


                 {  Program       to    d e m o n s t r a t et h e TCGetAttr       / T C S e t A t t/rCFMakeRaw         f u n c t i*
 * o n.s }


                 p r o c e d u r eShowTermios        ( v a r  t i o s: T e r m i o s) ;
                 b e g i n



                                                                                 229

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    WriteLn     ( ' I n p u t|_|F l a g|s_||_|:$|_|',h e x s t(rt i o s.c __i f l a g, 8 ) + # 1 3 ) ;
                    WriteLn     ( ' Output    |_|F l a g s|_|:$|_|',h e x s t r(t i o s.c __o f l a g, 8 ) ) ;
                    WriteLn     ( ' L i n e|_|F l a g s|_||_||_|:$|_|',h e x s(ttri o s.c __l f l a g, 8 ) ) ;
                    WriteLn     ( ' C o n t r o l|_|F l a g:s|_|$',h e x s t r( t i o s.c __c f l a g, 8 ) ) ;
                 end  ;


                 v a r
                    o l d i o s,
                    t i o s  :  T e r m i o s;
                 b e g i n
                    WriteLn     ( ' Old  |_|a t t r i b u t e:s') ;
                    TCGetAttr       ( 1 ,t i o s) ;
                    ShowTermios        ( t i o s) ;
                    o l d i o s:= t i o s;
                    W r i t e l n(' S e t t i n g|_|raw|_|t e r m i n a|l_|mode ') ;
                    CFMakeRaw       ( t i o s) ;
                    T C S e t A t t r( 1 ,TCSANOW    , t i o s) ;
                    WriteLn     ( ' C u r r e n t|_|a t t r i b u t e:s') ;
                    TCGetAttr       ( 1 ,t i o s) ;
                    ShowTermios        ( t i o s) ;
                    T C S e t A t t r( 1 ,TCSANOW    , o l d i o s) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.115          TCGetPGrp

Declaration:      Function  TCGetPGrp  (Fd:longint;var  Id:longint)  :    boolean;

Description:      TCGetPGrp returns the process group ID of a foreground process group in Id The function
                 returns True if the call was succesfull, False otherwise

       Errors:    Errors are reported in LinuxError

     See also:    termios (2)
                 11.3.116          TCSendBreak

Declaration:      Function  TCSendBreak  (Fd,Duration:longint)  :    Boolean;

Description:      TCSendBreak Sends zero-valued bits on an asynchrone serial connection decsribed by file-
                 descriptor Fd, for duration Duration.  The function returns True if the action was performed
                 successfully, False otherwise.

       Errors:    Errors are reported in LinuxError.

     See also:    termios (2)
                 11.3.117          TCSetAttr

Declaration:      Function  TCSetAttr  (Fd:longint;OptAct:longint;var  Tios:TermIOS)  :  Boolean;

Description:      TCSetAttr Sets the terminal parameters you specify in a TermIOS structure Tios for the
                 terminal referred to by the file descriptor Fd.  OptAct specifies an optional action when the
                 set need to be done, this could be one of the following pre-defined values:

                 TCSANOW             set immediately.

                 TCSADRAIN              wait for output.
                                                                                 230

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 TCSAFLUSH              wait for output and discard all input not yet read.

                 The function Returns True if the call was succesfull, False otherwise.

       Errors:    Errors are reported in LinuxError.

     See also:    TCGetAttr (229), termios (2)


                 For an example, see TCGetAttr (229).
                 11.3.118          TCSetPGrp

Declaration:      Function  TCSetPGrp  (Fd,Id:longint)  :    boolean;

Description:      TCSetPGrp  Sets  the  Process  Group  Id  to  Id.   The  function  returns  True  if  the  call  was
                 successful, False otherwise.

       Errors:    Errors are returned in LinuxError.

     See also:    TCGetPGrp (230), termios (2)


                 For an example, see TCGetPGrp (230).
                 11.3.119          TTYName

Declaration:      Function  TTYName  (var  f)  :    String;

Description:      Returns the name of the terminal pointed to by f.  f must be a terminal.  f can be of type:

                     1.longint for file handles;

                     2.Text for text variables such as input etc.

       Errors:    Returns an empty string in case of an error.  Linuxerror may be set to indicate what error
                 occurred, but this is uncertain.

     See also:    IsATTY (206),IOCtl (205)
                 11.3.120          TellDir

Declaration:      Function  TellDir  (p:pdir)  :    longint;

Description:      TellDir returns the current location in the directory structure pointed to by p.  It returns
                 -1 on failure.

       Errors:    Errors are returned in LinuxError.

     See also:    CloseDir (177), ReadDir (217), SeekDir (219), OpenDir (214), telldir (3)


                 For an example, see OpenDir (214).



                                                                                 231

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.121          Umask

Declaration:      Function  Umask  (Mask  :    Integer)  :    Integer;

Description:      Change the file creation mask for the current user to Mask.  The current mask is returned.

       Errors:    None

     See also:    Chmod (175), Umask (2)


                 Listing:  linuxex/ex27.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example27      ;


                 {  Program       to    d e m o n s t r a t et h e Umask      f u n c t i o n.  }


                 Uses     l i n u x;


                 b e g i n
                    W r i t e l n ( ' Old  |_|Umask  |_|was  |_|: |_|',Umask  ( O c t a l( 1 1 1 ) ) ) ;
                    WRiteln       ( 'New   |_|Umask  |_|i s|_||_|: |_|',O c t a(l1 1 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.122          Uname

Declaration:      Procedure  Uname  (var  unamerec:utsname);

Description:      Uname  gets  the  name  and  configuration  of  the  current  linux  kernel,  and  returns  it  in
                 unamerec.

       Errors:    LinuxError is used to report errors.

     See also:    GetHostName (200), GetDomainName (197), uname (2)
                 11.3.123          UnLink

Declaration:      Function  UnLink  (Var  Path)  :    Boolean;

Description:      UnLink decreases the link count on file Path.  Path can be of type PathStr or PChar.  If the
                 link count is zero,  the file is removed from the disk.  The function returns True if the call
                 was succesfull, False if the call failed.

       Errors:    Errors are returned in LinuxError.

                 sys___eaccess     You have no write access right in the directory containing Path, or you have
                       no search permission in one of the directory components of  Path.

                 sys___eperm      The directory containing pathname has the sticky-bit set and the process's ef-
                       fective uid is neither the uid of the file to be deleted nor that of the directory containing
                       it.

                 sys___enoent     A component of the path doesn't exist.

                 sys___enotdir     A directory component of the path is not a directory.

                 sys___eisdir   Path refers to a directory.

                 sys___enomem        Insufficient kernel memory.

                 sys___erofs   Path is on a read-only filesystem.

     See also:    Link (209), SymLink (226), Unlink (2)


                 For an example, see Link (209).



                                                                                 232

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.124          Utime

Declaration:      Function  Utime  (path  :    pathstr;  utim  :    utimbuf)  :    Boolean;

Description:      Utime  sets  the  access  and  modification  times  of  a  file.   the  utimbuf  record  contains  2
                 fields, actime, and modtime, both of type Longint.  They should be filled with an epoch-like
                 time, specifying, respectively, the last access time, and the last modification time.  For some
                 filesystem (most notably, FAT), these times are the same.

       Errors:    Errors are returned in LinuxError.

                 sys___eaccess     One of the directories in Path has no search (=execute) permission.

                 sys___enoent     A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                       non-existent directory.

                 Other errors may occur, but aren't documented.

     See also:    GetEpochTime (199), Chown (174), Access (169), utime (() 2)


                 Listing:  linuxex/ex25.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example25      ;


                 {  Program       to    d e m o n s t r a t et h e UTime      f u n c t i o n.  }


                 Uses     l i n u x;


                 Var    utim    :   u t i m b u f;
                        y e a r,month    , day  , h o u r, m i n u t e,s e c o n d :  Word    ;


                 b e g i n
                    {   S e t  a c c e s s and    m o d i f i c a t i o nt i m e o f   e x e c u t a b l es o u r c e}
                    GetTime       ( h o u r, m i n u t e,s e c o n d) ;
                    GetDate       ( y e a r, month   , day  ) ;
                    utim   . a c t i m e:= L o c a l T o E p o c(hy e a r,month    , day  , h o u r,m i n u t e, s e c o n d) ;
                    utim   . modtime     :=  utim   .a c t i m e;
                    i f  not    Utime    ( ' ex25   .pp  ' ,utim   )   then
                        w r i t e l n( ' C a l l|_|to|_|UTime   |_|f a i l e|d_|!)'
                    e l s e
                        b e g i n
                        Write     ( ' S e t|_|a c c e s|s_|and|_|m o d i f i c a t i o|n_|t i m|e_s|to|_|: |_|') ;
                        Write     ( Hour   : 2 ,' : ', m i n u t e: 2 ,' : ', s e c o n d,' , |_|') ;
                        W r i t e l n( Day   : 2 ,' / ', month    : 2 ,' / ', y e a r: 4 ) ;
                        end  ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 11.3.125          WaitPid

Declaration:      Function  WaitPid  (Pid  :    longint;  Status  :    pointer;  Options  :    Integer)  :    Longint;

Description:      WaitPid waits for a child process with process ID Pid to exit.  The value of Pid can be one
                 of the following:

                 Pid < -1    Causes  WaitPid  to  wait  for  any  child  process  whose  process  group  ID  equals  the
                       absolute value of  pid.

                 Pid = -1     Causes WaitPid to wait for any child process.

                                                                                 233

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Pid = 0     Causes WaitPid to wait for any child process whose process group ID equals the
                       one of the calling process.

                 Pid > 0    Causes WaitPid to wait for the child whose process ID equals the value of  Pid.

                 The Options parameter can be used to specify further how WaitPid behaves:

                 WNOHANG             Causes Waitpid to return immediately if no child has exited.

                 WUNTRACED               Causes WaitPid to return also for children which are stopped, but whose
                       status has not yet been reported.

                 Upon return, it returns the exit status of the process, or -1 in case of failure.

       Errors:    Errors are returned in LinuxError.

     See also:    Fork (195), Execve (184), waitpid (2)


                 For an example, see Fork (195).
                 11.3.126          WritePort

Declaration:      Procedure  WritePort  (Port  :    Longint;  Value  :    Byte);  Procedure  WritePort  (Port
                 :    Longint;  Value  :    Word);  Procedure  WritePort  (Port  :    Longint;  Value  :    Longint);

Description:      WritePort writes Value - 1 byte, Word or longint - to port Port.

                 Note:  You need permission to write to a port.  This permission can be set with root permis-
                 sion with the IOperm call.

       Errors:    In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                 Violation) will occur.

     See also:    IOperm (205), WritePortB (234), WritePortL (235), WritePortW (235), ReadPortB (218), Read-
                 PortL (218), ReadPortW (219)
                 11.3.127          WritePortB

Declaration:      Procedure  WritePortB  (Port  :    Longint;  Value  :    Byte);  Procedure  WritePortB  (Port
                 :    Longint;  Var  Buf;  Count:    longint);

Description:      The first form of  WritePortB writes 1 byte to port Port.  The second form writes Count
                 bytes from Buf to port Port.

                 Note:  You need permission to write to a port.  This permission can be set with root permis-
                 sion with the IOperm call.

       Errors:    In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                 Violation) will occur.

     See also:    IOperm (205), WritePort (234), WritePortL (235), WritePortW (235), ReadPortB (218), Read-
                 PortL (218), ReadPortW (219)



                                                                                 234

                 __________________________________________________________________________11.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 11.3.128          WritePortL

Declaration:      Procedure  WritePortL  (Port  :    Longint;  Value  :    Longint);  Procedure  WritePortL
                 (Port  :    Longint;  Var  Buf;  Count:    longint);

Description:      The first form of  WritePortB writes 1 byte to port Port.  The second form writes Count
                 bytes from Buf to port Port.

                 Note:  You need permission to write to a port.  This permission can be set with root permis-
                 sion with the IOperm call.

       Errors:    In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                 Violation) will occur.

     See also:    IOperm (205), WritePort (234), WritePortB (234), WritePortW (235), ReadPortB (218), Read-
                 PortL (218), ReadPortW (219)
                 11.3.129          WritePortW

Declaration:      Procedure  WritePortW  (Port  :    Longint;  Var  Buf;  Count:    longint);  Procedure  WritePortW
                 (Port  :    Longint;  Value  :    Word);

Description:      The first form of  WritePortB writes 1 byte to port Port.  The second form writes Count
                 bytes from Buf to port Port.

                 Note:  You need permission to write to a port.  This permission can be set with root permis-
                 sion with the IOperm call.

       Errors:    In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                 Violation) will occur.

     See also:    IOperm (205), WritePort (234), WritePortL (235), WritePortB (234), ReadPortB (218), Read-
                 PortL (218), ReadPortW (219)


                                                                                 235


Chapter   12


The   MATH   unit



This  chapter  describes  the  math  unit.   The  math  unit  was  initially  written  by  Florian
Klaempfl.  It provides mathematical functions which aren't covered by the system unit.

This chapter starts out with a definition of all types and constants that are defined,  after
which an overview is presented of the available functions, grouped by category, and the last
part contains a complete explanation of each function.

The following things must be taken into account when using this unit:


   1.  This unit is compiled in Object Pascal mode so all integers are 32 bit.

   2.  Some overloaded functions exist for data arrays of integers and floats.  When using the
       address operator (@) to pass an array of data to such a function, make sure the address
       is typecasted to the right type, or turn on the 'typed address operator' feature.  failing
       to do so, will cause the compiler not be able to decide which function you want to call.
12.1          Constants  and  types


The following types are defined in the math unit:


Type
   Float  =  Extended;
   PFloat  =  ^FLoat


All  calculations  are  done  with  the  Float  type.   This  allows  to  recompile  the  unit  with  a
different float type to obtain a desired precision.  The pointer type is used in functions that
accept an array of values of arbitrary length.


Type
    TPaymentTime  =  (PTEndOfPeriod,PTStartOfPeriod);


TPaymentTime is used in the financial calculations.


Type
    EInvalidArgument  =  Class(EMathError);


The EInvalidArgument exception is used to report invalid arguments.

                                                            236

__________________________________________________________________________12.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
12.2          Function  list  by  category


What follows is a listing of the available functions, grouped by category.  For each function
there is a reference to the page where you can find the function.
12.2.1        Min/max  determination

Functions to determine the minimum or maximum of numbers:


Name_______________________________________________Description_________________________________________________Page___________

  max                              Maximum of 2 values                                                        250

  maxIntValue                      Maximum of an array of integer values                                251

  maxvalue                         Maximum of an array of values                                           251

  min                              Minimum of 2 values                                                         254

  minIntValue                      Minimum of an array of integer values                                 254

  minvalue                         Minimum of an array of values                                           255
12.2.2        Angle  conversion


Name_______________________________________________Description_________________________________________________Page___________

  cycletorad                       convert cycles to radians                                                    243

  degtograd                        convert degrees to grads                                                    244

  degtorad                         convert degrees to radians                                                  244

  gradtodeg                        convert grads to degrees                                                    246

  gradtorad                        convert grads to radians                                                    246

  radtocycle                       convert radians to cycles                                                    259

  radtodeg                         convert radians to degrees                                                  259

  radtograd                        convert radians to grads                                                    260
12.2.3        Trigoniometric  functions


Name_______________________________________________Description_________________________________________________Page___________

  arccos                           calculate reverse cosine                                                      239

  arcsin                           calculate reverse sine                                                         240

  arctan2                          calculate reverse tangent                                                    240

  cotan                            calculate cotangent                                                           243

  sincos                           calculate sine and cosine                                                    261

  tan                              calculate tangent                                                              265



                                                                237

__________________________________________________________________________12.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
12.2.4        Hyperbolic  functions


Name_______________________________________________Description_________________________________________________Page___________

  arcosh                           caculate reverse hyperbolic cosine                                       239

  arsinh                           caculate reverse hyperbolic sine                                          241

  artanh                           caculate reverse hyperbolic tangent                                     241

  cosh                             calculate hyperbolic cosine                                                 242

  sinh                             calculate hyperbolic sine                                                    262

  tanh                             calculate hyperbolic tangent                                               265
12.2.5        Exponential  and  logarithmic  functions


Name_______________________________________________Description_________________________________________________Page___________

  intpower                         Raise float to integer power                                                247

  ldexp                            Calculate 2p x                                                                   248

  lnxp1                            calculate log(x+1)                                                           248

  log10                            calculate 10-base log                                                         249

  log2                             calculate 2-base log                                                           249

  logn                             calculate N-base log                                                          250

  power                            raise float to arbitrary power                                              258
12.2.6        Number  converting


Name_______________________________________________Description_________________________________________________Page___________

  ceil                             Round to infinity                                                              242

  floor                            Round to minus infinity                                                     245

  frexp                            Return mantissa and exponent                                           245
12.2.7        Statistical  functions


Name_______________________________________________Description_________________________________________________Page___________

  mean                             Mean of values                                                                 252

  meanandstddev                    Mean and standard deviation of values                                253

  momentskewkurtosis               Moments, skew and kurtosis                                               256

  popnstddev                       Population standarddeviation                                             257

  popnvariance                     Population variance                                                          258

  randg                            Gaussian distributed randum value                                     260

  stddev                           Standard deviation                                                           262

  sum                              Sum of values                                                                  263

  sumofsquares                     Sum of squared values                                                       263



                                                                238

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                   sumsandsquares                   Sum of values and squared values                                       264

                   totalvariance                    Total variance of values                                                     266

                   variance                         variance of values                                                             *
 *266
                 12.2.8        Geometrical  functions


                 Name_______________________________________________Description_________________________________________________Pag*
 *e___________

                   hypot                            Hypotenuse of triangle                                                      247

                   norm                             Euclidian norm                                                                2*
 *56
                 12.3          Functions  and  Procedures



                 12.3.1        arccos

Declaration:      Function  arccos(x  :    float)  :    float;

Description:      Arccos returns the inverse cosine of its argument x.  The argument x should lie between -1
                 and 1 (borders included).

       Errors:    If the argument x is not in the allowed range, an EInvalidArgument exception is raised.

     See also:    arcsin (240), arcosh (239), arsinh (241), artanh (241)


                 Listing:  mathex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;


                 {  Program       to    d e m o n s t r a t et h e a r c c o s  f u n c t i o n.  }


                 Uses    math    ;


                    Procedure         WriteRadDeg        (X   :   f l o a t) ;


                    b e g i n
                        W r i t e l n(X : 8 : 5 ,' |_|r a|d_|= |_|',r a d t o d(exg) : 8 : 5 ,' |_|d e g r e e.s')
                    end   ;


                 b e g i n
                    WriteRadDeg          ( a r c c o s( 1 ) ) ;
                    WriteRadDeg          ( a r c c o s(s q r t( 3 ) / 2 ) ) ;
                    WriteRadDeg          ( a r c c o s(s q r t( 2 ) / 2 ) ) ;
                    WriteRadDeg          ( a r c c o s( 1 / 2 ) ) ;
                    WriteRadDeg          ( a r c c o s( 0 ) ) ;
                    WriteRadDeg          ( a r c c o s( - 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.2        arcosh

Declaration:      Function  arcosh(x  :    float)  :    float;  Function  arccosh(x  :    float)  :    float;

Description:      Arcosh returns the inverse hyperbolic cosine of its argument x.  The argument x should be
                 larger than 1.

                 The arccosh variant of this function is supplied for Delphicompatibility.



                                                                                 239

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    If the argument x is not in the allowed range, an EInvalidArgument exception is raised.

     See also:    cosh (242), sinh (262), arcsin (240), arsinh (241), artanh (241), tanh (265)


                 Listing:  mathex/ex3.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example3      ;


                 {  Program       to    d e m o n s t r a t et h e a r c o s h  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(a r c o s h( 1 ) ) ;
                    W r i t e l n(a r c o s h( 2 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.3        arcsin

Declaration:      Function  arcsin(x  :    float)  :    float;

Description:      Arcsin returns the inverse sine of its argument x.  The argument x should lie between -1
                 and 1.

       Errors:    If the argument x is not in the allowed range, an EInvalidArgument exception is raised.

     See also:    arccos (239), arcosh (239), arsinh (241), artanh (241)


                 Listing:  mathex/ex2.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;


                 {  Program       to    d e m o n s t r a t et h e  a r c s i n f u n c t i o n.  }


                 Uses    math    ;


                    Procedure         WriteRadDeg        (X   :   f l o a t) ;


                    b e g i n
                        W r i t e l n(X : 8 : 5 ,' |_|r a|d_|= |_|',r a d t o d(exg) : 8 : 5 ,' |_|d e g r e e.s')
                    end   ;


                 b e g i n
                    WriteRadDeg          ( a r c s i n( 1 ) ) ;
                    WriteRadDeg          ( a r c s i n(s q r t( 3 ) / 2 ) ) ;
                    WriteRadDeg          ( a r c s i n(s q r t( 2 ) / 2 ) ) ;
                    WriteRadDeg          ( a r c s i n( 1 / 2 ) ) ;
                    WriteRadDeg          ( a r c s i n( 0 ) ) ;
                    WriteRadDeg          ( a r c s i n( - 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.4        arctan2

Declaration:      Function  arctan2(x,y  :    float)  :    float;


                                                                                 240

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      arctan2  calculates  arctan(y/x),  and  returns  an  angle  in  the  correct  quadrant.  The  re-
                 turned angle will be in the range -ss to ss radians.  The values of  x and y must be between
                 -2^64 and 2^64, moreover x should be different from zero.

                 On Intel systems this function is implemented with the native intel fpatan instruction.

       Errors:    If  x is zero, an overflow error will occur.

     See also:    arccos (239), arcosh (239), arsinh (241), artanh (241)


                 Listing:  mathex/ex6.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;


                 {  Program       to    d e m o n s t r a t et h e a r c t a n 2 f u n c t i o n.  }


                 Uses    math    ;


                    Procedure         WriteRadDeg        (X   :   f l o a t) ;


                    b e g i n
                        W r i t e l n(X : 8 : 5 ,' |_|r a|d_|= |_|',r a d t o d(exg) : 8 : 5 ,' |_|d e g r e e.s')
                    end   ;


                 b e g i n
                    WriteRadDeg          ( a r c t a n 2( 1 , 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.5        arsinh

Declaration:      Function  arsinh(x  :    float)  :    float;  Function  arcsinh(x  :    float)  :    float;

Description:      arsinh returns the inverse hyperbolic sine of its argument x.

                 The arscsinh variant of this function is supplied for Delphicompatibility.

       Errors:    None.

     See also:    arcosh (239), arccos (239), arcsin (240), artanh (241)


                 Listing:  mathex/ex4.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example4      ;


                 {  Program       to    d e m o n s t r a t et h e a r s i n h  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(a r s i n h( 0 ) ) ;
                    W r i t e l n(a r s i n h( 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.6        artanh

Declaration:      Function  artanh(x  :    float)  :    float;  Function  arctanh(x  :    float)  :    float;
                                                                                 241

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      artanh returns the inverse hyperbolic tangent of its argument x, where x should lie in the
                 interval [-1,1], borders included.

                 The arctanh variant of this function is supplied for Delphicompatibility.

       Errors:    In case x is not in the interval [-1,1], an EInvalidArgument exception is raised.

     See also:    arcosh (239), arccos (239), arcsin (240), artanh (241)

       Errors:

     See also:


                 Listing:  mathex/ex5.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example5      ;


                 {  Program       to    d e m o n s t r a t et h e a r t a n h  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(a r t a n h( 0 ) ) ;
                    W r i t e l n(a r t a n h( 0 . 5 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.7        ceil

Declaration:      Function  ceil(x  :    float)  :    longint;

Description:      Ceil returns the lowest integer number greater than or equal to x.  The absolute value of
                 x should be less than maxint.

       Errors:    If the asolute value of  x is larger than maxint, an overflow error will occur.

     See also:    floor (245)


                 Listing:  mathex/ex7.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example7      ;


                 {  Program       to    d e m o n s t r a t et h e C e i l  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(C e i l( - 3 . 7 ) ) ;  / / s h o u l d be   -3
                    W r i t e l n(C e i l( 3 . 7 ) ) ;   / /  s h o u l d be   4
                    W r i t e l n(C e i l( - 4 . 0 ) ) ;  / / s h o u l d be   -4
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.8        cosh

Declaration:      Function  cosh(x  :    float)  :    float;

Description:      Cosh returns the hyperbolic cosine of it's argument x.
                                                                                 242

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    None.

     See also:    arcosh (239), sinh (262), arsinh (241)


                 Listing:  mathex/ex8.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;


                 {  Program       to    d e m o n s t r a t et h e c o s h  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(Cosh   ( 0 ) ) ;
                    W r i t e l n(Cosh   ( 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.9        cotan

Declaration:      Function  cotan(x  :    float)  :    float;

Description:      Cotan returns the cotangent of it's argument x.  x should be different from zero.

       Errors:    If  x is zero then a overflow error will occur.

     See also:    tanh (265)


                 Listing:  mathex/ex9.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example9      ;


                 {  Program       to    d e m o n s t r a t et h e c o t a n  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(c o t a n( p i/ 2 ) ) ;
                    W r i t e l n(c o t a n( p i/ 3 ) ) ;
                    W r i t e l n(c o t a n( p i/ 4 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.10         cycletorad

Declaration:      Function  cycletorad(cycle  :    float)  :    float;

Description:      Cycletorad transforms it's argument cycle (an angle expressed in cycles) to radians.  (1
                 cycle is 2ss radians).

       Errors:    None.

     See also:    degtograd (244), degtorad (244), radtodeg (259), radtograd (260), radtocycle (259)


                 Listing:  mathex/ex10.pp
                                                                                 243

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;


                 {  Program       to    d e m o n s t r a t et h e  c y c l e t o r a df u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(cos  ( c y c l e t o r a d( 1 / 6 ) ) ) ;  / /S h o u l d p r i n t 1 / 2
                    w r i t e l n(cos  ( c y c l e t o r a d( 1 / 8 ) ) ) ;  / /s h o u l d be   s q r t( 2 ) / 2
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.11         degtograd

Declaration:      Function  degtograd(deg  :    float)  :    float;

Description:      Degtograd transforms it's argument deg (an angle in degrees) to grads.

                 (90 degrees is 100 grad.)

       Errors:    None.

     See also:    cycletorad (243), degtorad (244), radtodeg (259), radtograd (260), radtocycle (259)


                 Listing:  mathex/ex11.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example11      ;


                 {  Program       to    d e m o n s t r a t et h e d e g t o g r a d f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(d e g t o g r a d( 9 0 ) ) ;
                    w r i t e l n(d e g t o g r a d( 1 8 0 ) ) ;
                    w r i t e l n(d e g t o g r a d( 2 7 0 ) )
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.12         degtorad

Declaration:      Function  degtorad(deg  :    float)  :    float;

Description:      Degtorad converts it's argument deg (an angle in degrees) to radians.

                 (pi radians is 180 degrees)

       Errors:    None.

     See also:    cycletorad (243), degtograd (244), radtodeg (259), radtograd (260), radtocycle (259)


                 Listing:  mathex/ex12.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example12      ;


                 {  Program       to    d e m o n s t r a t et h e d e g t o r a d f u n c t i o n.  }


                 Uses    math    ;



                                                                                 244

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________


                 b e g i n
                    w r i t e l n(d e g t o r a d( 4 5 ) ) ;
                    w r i t e l n(d e g t o r a d( 9 0 ) ) ;
                    w r i t e l n(d e g t o r a d( 1 8 0 ) ) ;
                    w r i t e l n(d e g t o r a d( 2 7 0 ) ) ;
                    w r i t e l n(d e g t o r a d( 3 6 0 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.13         floor

Declaration:      Function  floor(x  :    float)  :    longint;

Description:      Floor returns the largest integer smaller than or equal to x.  The absolute value of x should
                 be less than maxint.

       Errors:    If  x is larger than maxint, an overflow will occur.

     See also:    ceil (242)


                 Listing:  mathex/ex13.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example13      ;


                 {  Program       to    d e m o n s t r a t et h e  f l o o r f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(C e i l( - 3 . 7 ) ) ;  / / s h o u l d be   -4
                    W r i t e l n(C e i l( 3 . 7 ) ) ;   / /  s h o u l d be   3
                    W r i t e l n(C e i l( - 4 . 0 ) ) ;  / / s h o u l d be   -4
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.14         frexp

Declaration:      Procedure  frexp(x  :    float;var  mantissa,exponent  :    float);

Description:      Frexp returns the mantissa and exponent of it's argument x in mantissa and exponent.

       Errors:    None

     See also:


                 Listing:  mathex/ex14.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example14      ;


                 {  Program       to    d e m o n s t r a t et h e f r e x p  f u n c t i o n.  }


                 Uses    math    ;


                 Procedure        d o f r e x p(Const     X   :   e x t e n d e d) ;


                 v a r  man    :  e x t e n d e d;
                        exp  :   i n t e g e r;



                                                                                 245

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________


                 b e g i n
                    man   : = 0 ;
                    exp   : = 0 ;
                    f r e x p( x ,man  , exp   ) ;
                    w r i t e( x ,' |_|has |_|') ;
                    W r i t e l n(' m a n t i s s a|_|',man , ' |_|and |_|e x p o n e n|t_|',exp ) ;
                 end  ;



                 b e g i n
                 / /      d o f r e x p( 1 . 0 0 ) ;
                      d o f r e x p( 1 . 0 2e-1);
                      d o f r e x p( 1 . 0 3e-2);
                      d o f r e x p( 1 . 0 2e1 ) ;
                      d o f r e x p( 1 . 0 3e2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.15         gradtodeg

Declaration:      Function  gradtodeg(grad  :    float)  :    float;

Description:      Gradtodeg converts its argument grad (an angle in grads) to degrees.

                 (100 grad is 90 degrees)

       Errors:    None.

     See also:    cycletorad (243), degtograd (244), radtodeg (259), radtograd (260), radtocycle (259), gradtorad
                 (246)


                 Listing:  mathex/ex15.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example15      ;


                 {  Program       to    d e m o n s t r a t et h e g r a d t o d e g f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(g r a d t o d e g( 1 0 0 ) ) ;
                    w r i t e l n(g r a d t o d e g( 2 0 0 ) ) ;
                    w r i t e l n(g r a d t o d e g( 3 0 0 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.16         gradtorad

Declaration:      Function  gradtorad(grad  :    float)  :    float;

Description:      Gradtorad converts its argument grad (an angle in grads) to radians.

                 (200 grad is pi degrees).

       Errors:    None.

     See also:    cycletorad (243), degtograd (244), radtodeg (259), radtograd (260), radtocycle (259), gradtodeg
                 (246)
                                                                                 246

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Listing:  mathex/ex16.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example16      ;


                 {  Program       to    d e m o n s t r a t et h e g r a d t o r a d f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(g r a d t o r a d( 1 0 0 ) ) ;
                    w r i t e l n(g r a d t o r a d( 2 0 0 ) ) ;
                    w r i t e l n(g r a d t o r a d( 3 0 0 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.17         hypot

Declaration:      Function  hypot(x,y  :    float)  :    float;

Description:      Hypot returns the hypotenuse of the triangle where the sides adjacent to the square angle
                 have lengths x and y.

                 The function uses Pythagoras' rule for this.

       Errors:    None.

     See also:


                 Listing:  mathex/ex17.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example17      ;


                 {  Program       to    d e m o n s t r a t et h e h y p o t  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(h y p o t( 3 , 4 ) ) ;  / / s h o u l d be   5
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.18         intpower

Declaration:      Function  intpower(base  :    float;exponent  :    longint)  :    float;

Description:      Intpower returns base to the power exponent, where exponent is an integer value.

       Errors:    If  base is zero and the exponent is negative, then an overflow error will occur.

     See also:    power (258)


                 Listing:  mathex/ex18.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example18      ;


                 {  Program       to    d e m o n s t r a t et h e i n t p o w e r f u n c t i o n.  }


                 Uses    math    ;
                                                                                 247

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________


                 Procedure        D o I n t p o w e r( X   :  e x t e n d e d; Pow    :   I n t e g e r) ;


                 b e g i n
                    w r i t e l n(X : 8 : 4 ,' ^ ',Pow   : 2 ,' |_|= |_|',i n t p o w e(rX, pow  ) : 8 : 4 ) ;
                 end  ;


                 b e g i n
                    d o i n t p o w e r( 0 . 0 , 0 ) ;
                    d o i n t p o w e r( 1 . 0 , 0 ) ;
                    d o i n t p o w e r( 2 . 0 , 5 ) ;
                    d o i n t p o w e r( 4 . 0 , 3 ) ;
                    d o i n t p o w e r( 2 . 0 , - 1 ) ;
                    d o i n t p o w e r( 2 . 0 , - 2 ) ;
                    d o i n t p o w e r( - 2 . 0 , 4 ) ;
                    d o i n t p o w e r( - 4 . 0 , 3 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.19         ldexp

Declaration:      Function  ldexp(x  :    float;p  :    longint)  :    float;

Description:      Ldexp returns 2p x.

       Errors:    None.

     See also:    lnxp1 (248), log10 (249),log2 (249),logn (250)


                 Listing:  mathex/ex19.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example19      ;


                 {  Program       to    d e m o n s t r a t et h e l d e x p  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(l d e x p( 2 , 4 ) : 8 : 4 ) ;
                    w r i t e l n(l d e x p( 0 . 5 , 3 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.20         lnxp1

Declaration:      Function  lnxp1(x  :    float)  :    float;

Description:      Lnxp1 returns the natural logarithm of  1+X. The result is more precise for small values of
                 x.  x should be larger than -1.

       Errors:    If x   -1 then an EInvalidArgument exception will be raised.

     See also:    ldexp (248), log10 (249),log2 (249),logn (250)


                 Listing:  mathex/ex20.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example20      ;

                                                                                 248

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 {  Program       to    d e m o n s t r a t et h e l n x p 1  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(l n x p 1( 0 ) ) ;
                    w r i t e l n(l n x p 1( 0 . 5 ) ) ;
                    w r i t e l n(l n x p 1( 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.21         log10

Declaration:      Function  log10(x  :    float)  :    float;

Description:      Log10 returns the 10-base logarithm of  X.

       Errors:    If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.

     See also:    ldexp (248), lnxp1 (248),log2 (249),logn (250)


                 Listing:  mathex/ex21.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example21      ;


                 {  Program       to    d e m o n s t r a t et h e l o g 1 0  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(Log10    ( 1 0 ) : 8 : 4 ) ;
                    W r i t e l n(Log10    ( 1 0 0 ) : 8 : 4 ) ;
                    W r i t e l n(Log10    ( 1 0 0 0 ) : 8 : 4 ) ;
                    W r i t e l n(Log10    ( 1 ) : 8 : 4 ) ;
                    W r i t e l n(Log10    ( 0 . 1 ) : 8 : 4 ) ;
                    W r i t e l n(Log10    ( 0 . 0 1 ) : 8 : 4 ) ;
                    W r i t e l n(Log10    ( 0 . 0 0 1 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.22         log2

Declaration:      Function  log2(x  :    float)  :    float;

Description:      Log2 returns the 2-base logarithm of  X.

       Errors:    If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.

     See also:    ldexp (248), lnxp1 (248),log10 (249),logn (250)


                 Listing:  mathex/ex22.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example22      ;


                 {  Program       to    d e m o n s t r a t et h e l o g 2  f u n c t i o n.  }


                 Uses    math    ;

                                                                                 249

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 b e g i n
                    W r i t e l n(Log2   ( 2 ) : 8 : 4 ) ;
                    W r i t e l n(Log2   ( 4 ) : 8 : 4 ) ;
                    W r i t e l n(Log2   ( 8 ) : 8 : 4 ) ;
                    W r i t e l n(Log2   ( 1 ) : 8 : 4 ) ;
                    W r i t e l n(Log2   ( 0 . 5 ) : 8 : 4 ) ;
                    W r i t e l n(Log2   ( 0 . 2 5 ) : 8 : 4 ) ;
                    W r i t e l n(Log2   ( 0 . 1 2 5 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.23         logn

Declaration:      Function  logn(n,x  :    float)  :    float;

Description:      Logn returns the n-base logarithm of  X.

       Errors:    If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.

     See also:    ldexp (248), lnxp1 (248),log10 (249),log2 (249)


                 Listing:  mathex/ex23.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example23      ;


                 {  Program       to    d e m o n s t r a t et h e l o g n  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    W r i t e l n(Logn   ( 3 , 4 ) : 8 : 4 ) ;
                    W r i t e l n(Logn   ( 2 , 4 ) : 8 : 4 ) ;
                    W r i t e l n(Logn   ( 6 , 9 ) : 8 : 4 ) ;
                    W r i t e l n(Logn   ( exp  ( 1 ) ,exp   ( 1 ) ) : 8 : 4 ) ;
                    W r i t e l n(Logn   ( 0 . 5 , 1 ) : 8 : 4 ) ;
                    W r i t e l n(Logn   ( 0 . 2 5 , 3 ) : 8 : 4 ) ;
                    W r i t e l n(Logn   ( 0 . 1 2 5 , 5 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.24         max

Declaration:      Function  max(Int1,Int2:Cardinal):Cardinal;  Function  max(Int1,Int2:Integer):Integer;

Description:      Max returns the maximum of  Int1 and Int2.

       Errors:    None.

     See also:    min (254), maxIntValue (251), maxvalue (251)


                 Listing:  mathex/ex24.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example24      ;


                 {  Program       to    d e m o n s t r a t et h e max    f u n c t i o n.  }


                 Uses    math    ;

                                                                                 250

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Var
                    A ,B   :   C a r d i n a l;


                 b e g i n
                    A : = 1 ;b : = 2 ;
                    w r i t e l n(max  ( a ,b  ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.25         maxIntValue

Declaration:      function  MaxIntValue(const  Data:    array  of  Integer):    Integer;

Description:      MaxIntValue returns the largest integer out of the Data array.

                 This function is provided for Delphicompatibility, use the maxvalue (251) function instead.

       Errors:    None.

     See also:    maxvalue (251), minvalue (255), minIntValue (254)


                 Listing:  mathex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example25      ;


                 {  Program       to    d e m o n s t r a t et h e M a x I n t V a l u ef u n c t i o n.  }


                 {  Make     s o r e  i n t e g e r i s  3 2  b i t}
                 {$mode      o b j f p c}


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   I n t e g e r;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i] : =Random     ( I)-  Random     ( 1 0 0 ) ;
                    W r i t e l n(M a x I n t V a l u(eE x A r r a y) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.26         maxvalue

Declaration:      Function  maxvalue(const  data  :    array  of  float)  :    float;  Function  maxvalue(const
                 data  :    array  of  Integer)  :    Integer;  Function  maxvalue(const  data  :    PFloat;
                 Const  N  :  Integer)  :    float;  Function  maxvalue(const  data  :    PInteger;  Const  N
                 :  Integer)  :    Integer;

Description:      Maxvalue  returns  the  largest  value  in  the  data  array  with  integer  or  float  values.   The
                 return value has the same type as the elements of the array.

                 The third and fourth forms accept a pointer to an array of  N integer or float values.

       Errors:    None.



                                                                                 251

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
     See also:    maxIntValue (251), minvalue (255), minIntValue (254)


                 Listing:  mathex/ex26.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example26      ;


                 {  Program       to    d e m o n s t r a t et h e MaxValue        f u n c t i o n.  }


                 {  Make     s o r e  i n t e g e r i s  3 2  b i t}
                 {$mode      o b j f p c}


                 Uses    math    ;


                 Type
                    T E x F l o a t A r r a y=  Array    [ 1 . . 1 0 0 ] of   F l o a t;
                    T E x I n t A r r a y=   Array    [ 1 . . 1 0 0 ]of   I n t e g e r;


                 Var
                    I   :  I n t e g e r;
                    E x F l o a t A r r a y:  T E x F l o a t A r r a;y
                    E x I n t A r r a y:   T E x I n t A r r a;y
                    A F L o a t A r r a y:   PFLoat    ;
                    A I n t A r r a y :  P I n t e g e r;
                 b e g i n
                    Randomize       ;
                    A F l o a t A r r a:y= @ E x F l o a t A r r a[y1 ] ;
                    A I n t A r r a y:= @ E x I n t A r r a[y1 ] ;
                    f o r  I :=1    to   1 0 0  do
                        E x F l o a t A r r a[yi] : = (Random    - Random     ) * 1 0 0 ;
                    f o r  I :=1    to   1 0 0  do
                        E x I n t A r r a[yi ] : =Random    ( I )- Random     ( 1 0 0 ) ;
                    W r i t e l n(' Max  |_|F l o a t|_||_||_||_||_||_||_|:,|_|'MaxValue(E x F l o a t A r r)a:y8 : 4 ) ;
                    W r i t e l n(' Max  |_|F l o a t|_||_||_|(b) |_|:,|_|'MaxValue  ( A F l o a t A r r a,y1 0 0 ) : 8 : 4 ) ;
                    W r i t e l n(' Max  |_|I n t e g e r|_||_||_||_||_|:,|_|'MaxValue(E x I n t A r r a)y: 8 ) ;
                    W r i t e l n(' Max  |_|I n t e g e|r_|(b) |_|: |_|',MaxValue    ( A I n t A r r a,y1 0 0 ) : 8 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.27         mean

Declaration:      Function  mean(const  data  :    array  of  float)  :    float;  Function  mean(const  data
                 :    PFloat;  Const  N  :  longint)  :    float;

Description:      Mean returns the average value of  data.

                 The second form accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    meanandstddev (253), momentskewkurtosis (256), sum (263)


                 Listing:  mathex/ex27.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example27      ;


                 {  Program       to    d e m o n s t r a t et h e Mean     f u n c t i o n.  }


                 Uses    math    ;



                                                                                 252

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    W r i t e l n(' Max   |_||_||_||_||_||_|:,|_|'MaxValue(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Min   |_||_||_||_||_||_|:,|_|'MinValue(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Mean   |_||_||_||_||_|:,|_|'Mean(E x A r r a)y: 8 : 4 ) ;
                    W r i t e l n(' Mean   |_|(b) |_|: |_|',Mean  (@ExArray       [ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.28         meanandstddev

Declaration:      Procedure  meanandstddev(const  data  :    array  of  float;  var  mean,stddev  :    float);
                 procedure  meanandstddev(const  data  :    PFloat;  Const  N  :  Longint;var  mean,stddev
                 :    float);

Description:      meanandstddev calculates the mean and standard deviation of data and returns the result
                 in mean and stddev, respectively.  Stddev is zero if there is only one value.

                 The second form accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    mean (252),sum (263), sumofsquares (263), momentskewkurtosis (256)


                 Listing:  mathex/ex28.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example28      ;


                 {  Program       to    d e m o n s t r a t et h e Meanandstddev            f u n c t i o n.  }


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   E x t e n d e d;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;
                    Mean   , s t d d e v :   E x t e n d e d;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    MeanAndStdDev          ( E x A r r a y,Mean   ,StdDev     ) ;
                    W r i t e l n(' Mean   |_||_||_||_||_||_||_|:,|_|'Mean: 8 : 4 ) ;
                    W r i t e l n(' StdDev     |_||_||_||_||_|:,|_|'StdDev: 8 : 4 ) ;
                    MeanAndStdDev          ( @ExArray      [ 1 ] , 1 0 0M,ean   ,StdDev     ) ;
                    W r i t e l n(' Mean   |_||_||_|(b) |_|:,|_|'Mean: 8 : 4 ) ;



                                                                                 253

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    W r i t e l n(' StdDev     |_|(b) |_|: |_|',StdDev   : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.29         min

Declaration:      Function  min(Int1,Int2:Cardinal):Cardinal;  Function  min(Int1,Int2:Integer):Integer;

Description:      min returns the smallest value of  Int1 and Int2;

       Errors:    None.

     See also:    max (250)


                 Listing:  mathex/ex29.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example29      ;


                 {  Program       to    d e m o n s t r a t et h e min    f u n c t i o n.  }


                 Uses    math    ;


                 Var
                    A ,B   :   C a r d i n a l;


                 b e g i n
                    A : = 1 ;b : = 2 ;
                    w r i t e l n(min  ( a ,b  ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.30         minIntValue

Declaration:      Function  minIntValue(const  Data:    array  of  Integer):    Integer;

Description:      MinIntvalue returns the smallest value in the Data array.

                 This function is provided for Delphicompatibility, use minvalue instead.

       Errors:    None

     See also:    minvalue (255), maxIntValue (251), maxvalue (251)


                 Listing:  mathex/ex30.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example30      ;


                 {  Program       to    d e m o n s t r a t et h e M i n I n t V a l u ef u n c t i o n.  }


                 {  Make     s o r e  i n t e g e r i s  3 2  b i t}
                 {$mode      o b j f p c}


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   I n t e g e r;


                 Var
                    I   :  I n t e g e r;



                                                                                 254

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i] : =Random     ( I)-  Random     ( 1 0 0 ) ;
                    W r i t e l n(M i n I n t V a l u(eE x A r r a y) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.31         minvalue

Declaration:      Function  minvalue(const  data  :    array  of  float)  :    float;  Function  minvalue(const
                 data  :    array  of  Integer)  :    Integer;  Function  minvalue(const  data  :    PFloat;
                 Const  N  :  Integer)  :    float;  Function  minvalue(const  data  :    PInteger;  Const  N
                 :  Integer)  :    Integer;

Description:      Minvalue  returns  the  smallest  value  in  the  data  array  with  integer  or  float  values.  The
                 return value has the same type as the elements of the array.

                 The third and fourth forms accept a pointer to an array of  N integer or float values.

       Errors:    None.

     See also:    maxIntValue (251), maxvalue (251), minIntValue (254)


                 Listing:  mathex/ex31.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example26      ;


                 {  Program       to    d e m o n s t r a t et h e MinValue        f u n c t i o n.  }


                 {  Make     s o r e  i n t e g e r i s  3 2  b i t}
                 {$mode      o b j f p c}


                 Uses    math    ;


                 Type
                    T E x F l o a t A r r a y=  Array    [ 1 . . 1 0 0 ] of   F l o a t;
                    T E x I n t A r r a y=   Array    [ 1 . . 1 0 0 ]of   I n t e g e r;


                 Var
                    I   :  I n t e g e r;
                    E x F l o a t A r r a y:  T E x F l o a t A r r a;y
                    A F l o a t A r r a y:   P F l o a t;
                    E x I n t A r r a y:   T E x I n t A r r a;y
                    A i n t A r r a y :  P I n t e g e r;


                 b e g i n
                    Randomize       ;
                    A F l o a t A r r a:y= @ E x F l o a t A r r a[y0 ] ;
                    A I n t A r r a y:= @ E x I n t A r r a[y0 ] ;
                    f o r  I :=1    to   1 0 0  do
                        E x F l o a t A r r a[yi] : = (Random    - Random     ) * 1 0 0 ;
                    f o r  I :=1    to   1 0 0  do
                        E x I n t A r r a[yi ] : =Random    ( I )- Random     ( 1 0 0 ) ;
                    W r i t e l n(' Min  |_|F l o a t|_||_||_||_||_||_||_|:,|_|'MinValue(E x F l o a t A r r)a:y8 : 4 ) ;
                    W r i t e l n(' Min  |_|F l o a t|_||_||_|(b) |_|:,|_|'MinValue  ( A F l o a t A r r a,y1 0 0 ) : 8 : 4 ) ;
                    W r i t e l n(' Min  |_|I n t e g e r|_||_||_||_||_|:,|_|'MinValue(E x I n t A r r a)y: 8 ) ;



                                                                                 255

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    W r i t e l n(' Min  |_|I n t e g e|r_|(b) |_|: |_|',MinValue    ( A i n t A r r a,y1 0 0 ) : 8 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.32         momentskewkurtosis

Declaration:      procedure  momentskewkurtosis(const  data  :    array  of  float;  var  m1,m2,m3,m4,skew,kurtosis
                 :    float);  procedure  momentskewkurtosis(const  data  :    PFloat;  Const  N  :  Integer;
                 var  m1,m2,m3,m4,skew,kurtosis  :    float);

Description:      momentskewkurtosis  calculates  the  4  first  moments  of  the  distribution  of  valuesin  data
                 and returns them in m1,m2,m3 and m4, as well as the skew and kurtosis.

       Errors:    None.

     See also:    mean (252), meanandstddev (253)


                 Listing:  mathex/ex32.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example32      ;


                 {  Program       to    d e m o n s t r a t et h e m o m e n t s k e w k u r t o s i sf u n c t i o.n }


                 Uses    math    ;


                 Var
                    D i s t A r r a y :  Array    [ 1 . . 1 0 0 0 ]of    f l o a t;
                    I   :  l o n g i n t;
                    m1  ,m2  ,m3  , m4 , skew   , k u r t o s i s :  f l o a t;


                 b e g i n
                    randomize       ;
                    f o r  I :=1    to   1 0 0 0  do
                        d i s t a r r a[yi ] : =random     ;
                    m o m e n t s k e w k u r t o s i(sD i s t A r r a,ym1, m2  ,m3  ,m4  , skew   , k u r t o s i s) ;


                    W r i t e l n ( ' 1 s t|_|moment    |_|: |_|',m1: 8 : 6 ) ;
                    W r i t e l n ( ' 2nd  |_|moment    |_|: |_|',m2: 8 : 6 ) ;
                    W r i t e l n ( ' 3rd  |_|moment    |_|: |_|',m3: 8 : 6 ) ;
                    W r i t e l n ( ' 4th  |_|moment    |_|: |_|',m4: 8 : 6 ) ;
                    W r i t e l n ( ' Skew   |_||_||_||_||_||_||_|:,|_|'skew: 8 : 6 ) ;
                    W r i t e l n ( ' k u r t o s i s|_||_||_|:,|_|'k u r t o s:i8s: 6 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.33         norm

Declaration:      Function  norm(const  data  :    array  of  float)  :    float;  Function  norm(const  data
                 :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Norm calculates the Euclidian norm of the array of data.  This equals sqrt(sumofsquares(data)).

                 The second form accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    sumofsquares (263)


                 Listing:  mathex/ex33.pp



                                                                                 256

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example33      ;


                 {  Program       to    d e m o n s t r a t et h e norm     f u n c t i o n.  }


                 Uses    math    ;


                 Type
                    TVector       =   Array    [ 1 . . 1 0 ]of    F l o a t;


                 Var
                    AVector       :   T v e c t o r;
                    I   :  l o n g i n t;


                 b e g i n
                   f o r  I:=1    to   1 0   do
                      A v e c t o r[i ] : =Random    ;
                   W r i t e l n(Norm  ( AVector      ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.34         popnstddev

Declaration:      Function  popnstddev(const  data  :    array  of  float)  :    float;  Function  popnstddev(const
                 data  :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Popnstddev returns the square root of the population variance of the values in the Data
                 array.  It returns zero if there is only one value.

                 The second form of this function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    popnvariance  (258),  mean  (252),  meanandstddev  (253),  stddev  (262),  momentskewkurtosis
                 (256)


                 Listing:  mathex/ex35.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example35      ;


                 {  Program       to    d e m o n s t r a t et h e PopnStdDev          f u n c t i o n.  }


                 Uses    Math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    W r i t e l n(' Max   |_||_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'MaxValue(E x)A:r8r:a4y) ;
                    W r i t e l n(' Min   |_||_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'MinValue(E x)A:r8r:a4y) ;
                    W r i t e l n(' Pop  . |_|s t d d e.v|_||_||_||_||_|:,|_|'PopnStdDev  ( E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Pop  . |_|s t d d e.v|_|(b) |_|: |_|',PopnStdDev      ( @ExArray      [ 1 ] , 1 0 0 ) : 8 : 4 )*
 * ;



                                                                                 257

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.35         popnvariance

Declaration:      Function  popnvariance(const  data  :    array  of  float)  :    float;  Function  popnvariance(const
                 data  :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Popnvariance returns the square root of the population variance of the values in the Data
                 array.  It returns zero if there is only one value.

                 The second form of this function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    popnstddev (257), mean (252), meanandstddev (253), stddev (262), momentskewkurtosis (256)


                 Listing:  mathex/ex36.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example36      ;


                 {  Program       to    d e m o n s t r a t et h e P o p n V a r i a n c ef u n c t i o n.  }


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    W r i t e l n(' Max   |_||_||_||_||_||_||_||_||_||_||_|:,|_|'MaxValue(E x A)r:r8a:y4 ) ;
                    W r i t e l n(' Min   |_||_||_||_||_||_||_||_||_||_||_|:,|_|'MinValue(E x A)r:r8a:y4 ) ;
                    W r i t e l n(' Pop  . |_|v a r. |_||_||_||_||_|:,|_|'P o p n V a r i(aEnxcAer r a)y: 8 : 4 ) ;
                    W r i t e l n(' Pop  . |_|v a r. |_|(b) |_|: |_|',P o p n V a r i a n(c@eExArray    [ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.36         power

Declaration:      Function  power(base,exponent  :    float)  :    float;

Description:      power raises base to the power power.  This is equivalent to exp(power*ln(base)).  There-
                 fore base should be non-negative.

       Errors:    None.

     See also:    intpower (247)


                 Listing:  mathex/ex34.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example34      ;

                                                                                 258

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 {  Program       to    d e m o n s t r a t et h e power      f u n c t i o n.  }


                 Uses    Math    ;


                 p r o c e d u r edopower     ( x , y  :   f l o a t) ;


                 b e g i n
                    w r i t e l n(x : 8 : 6 ,' ^ ', y : 8 : 6 ,' |_|= |_|',power ( x ,y ) : 8 : 6 )
                 end  ;


                 b e g i n
                    dopower      ( 2 , 2 ) ;
                    dopower      ( 2 , - 2 ) ;
                    dopower      ( 2 , 0 . 0 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.37         radtocycle

Declaration:      Function  radtocycle(rad  :    float)  :    float;

Description:      Radtocycle converts its argument rad (an angle expressed in radians) to an angle in cycles.

                 (1 cycle equals 2 pi radians)

       Errors:    None.

     See also:    degtograd (244), degtorad (244), radtodeg (259), radtograd (260), cycletorad (243)


                 Listing:  mathex/ex37.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example37      ;


                 {  Program       to    d e m o n s t r a t et h e  r a d t o c y c l ef u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(r a d t o c y c l e(2* p i ) : 8 : 6 ) ;
                    w r i t e l n(r a d t o c y c l e(p i) : 8 : 6 ) ;
                    w r i t e l n(r a d t o c y c l e(p i/ 2 ) : 8 : 6 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.38         radtodeg

Declaration:      Function  radtodeg(rad  :    float)  :    float;

Description:      Radtodeg converts its argument rad (an angle expressed in radians) to an angle in degrees.

                 (180 degrees equals pi radians)

       Errors:    None.

     See also:    degtograd (244), degtorad (244), radtocycle (259), radtograd (260), cycletorad (243)


                 Listing:  mathex/ex38.pp



                                                                                 259

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example38      ;


                 {  Program       to    d e m o n s t r a t et h e r a d t o d e g f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(r a d t o d e g(2* p i ) : 8 : 6 ) ;
                    w r i t e l n(r a d t o d e g(p i ) : 8 : 6 ) ;
                    w r i t e l n(r a d t o d e g(p i / 2 ) : 8 : 6 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.39         radtograd

Declaration:      Function  radtograd(rad  :    float)  :    float;

Description:      Radtodeg converts its argument rad (an angle expressed in radians) to an angle in grads.

                 (200 grads equals pi radians)

       Errors:    None.

     See also:    degtograd (244), degtorad (244), radtocycle (259), radtodeg (259), cycletorad (243)


                 Listing:  mathex/ex39.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example39      ;


                 {  Program       to    d e m o n s t r a t et h e r a d t o g r a d f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(r a d t o g r a d(2* p i ) : 8 : 6 ) ;
                    w r i t e l n(r a d t o g r a d(p i) : 8 : 6 ) ;
                    w r i t e l n(r a d t o g r a d(p i/ 2 ) : 8 : 6 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.40         randg

Declaration:      Function  randg(mean,stddev  :    float)  :    float;

Description:      randg returns a random number which - when produced in large quantities - has a Gaussian
                 distribution with mean mean and standarddeviation stddev.

       Errors:    None.

     See also:    mean (252), stddev (262), meanandstddev (253)


                 Listing:  mathex/ex40.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example40      ;


                 {  Program       to    d e m o n s t r a t et h e r a n d g  f u n c t i o n.  }


                 Uses    Math    ;



                                                                                 260

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 0 0 ]of    F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;
                    Mean   , s t d d e v :   F l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0 0 0 do
                        E x A r r a y[i] : = Randg    ( 1 , 0 . 2 ) ;
                    MeanAndStdDev          ( E x A r r a y,Mean   ,StdDev     ) ;
                    W r i t e l n(' Mean   |_||_||_||_||_||_||_|:,|_|'Mean: 8 : 4 ) ;
                    W r i t e l n(' StdDev     |_||_||_||_||_|:,|_|'StdDev: 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.41         sincos

Declaration:      Procedure  sincos(theta  :    float;var  sinus,cosinus  :    float);

Description:      Sincos calculates the sine and cosine of the angle theta, and returns the result in sinus
                 and cosinus.

                 On Intel hardware,  This calculation will be faster than making 2 calls to clculatet he sine
                 and cosine separately.

       Errors:    None.

     See also:    arcsin (240), arccos (239).


                 Listing:  mathex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example41      ;


                 {  Program       to    d e m o n s t r a t et h e s i n c o s  f u n c t i o n.  }


                 Uses    math    ;


                 Procedure        d o s i n c o s(A n g l e :   F l o a t) ;


                 Var
                    S i n e, C o s i n e :   F l o a t;


                 b e g i n
                    s i n c o s( a n g l e,s i n e, c o s i n e) ;
                    Write    ( 'A n g l e |_|: |_|',A n g l:e8 : 6 ) ;
                    Write    ( ' |_|S i n e|_|:,'s i n e: 8 : 6 ) ;
                    Write    ( ' |_|C o s i n|e_|:,'c o s i n e: 8 : 6 ) ;
                 end  ;


                 b e g i n
                    d o s i n c o s(p i ) ;
                    d o s i n c o s(p i / 2 ) ;
                    d o s i n c o s(p i / 3 ) ;
                    d o s i n c o s(p i / 4 ) ;
                    d o s i n c o s(p i / 6 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 261

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 12.3.42         sinh

Declaration:      Function  sinh(x  :    float)  :    float;

Description:      Sinh returns the hyperbolic sine of its argument x.

       Errors:

     See also:    cosh (242), arsinh (241), tanh (265), artanh (241)


                 Listing:  mathex/ex42.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example42      ;


                 {  Program       to    d e m o n s t r a t et h e s i n h  f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n
                    w r i t e l n(s i n h( 0 ) ) ;
                    w r i t e l n(s i n h( 1 ) ) ;
                    w r i t e l n(s i n h( - 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.43         stddev

Declaration:      Function  stddev(const  data  :    array  of  float)  :    float;  Function  stddev(const
                 data  :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Stddev returns the standard deviation of the values in Data.  It returns zero if there is only
                 one value.

                 The second form of the function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    mean (252), meanandstddev (253), variance (266), totalvariance (266)


                 Listing:  mathex/ex43.pp
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example40      ;


                 {  Program       to    d e m o n s t r a t et h e s t d d e v  f u n c t i o n.  }


                 Uses    Math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 0 0 ]of    F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0 0 0 do
                        E x A r r a y[i] : = Randg    ( 1 , 0 . 2 ) ;
                    W r i t e l n(' StdDev     |_||_||_||_||_|:,|_|'StdDev(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' StdDev     |_|(b) |_|: |_|',StdDev   (@ExArray      [ 0 ] , 1 0 0 0 0 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 262

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 12.3.44         sum

Declaration:      Function  sum(const  data  :    array  of  float)  :    float;  Function  sum(const  data
                 :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Sum returns the sum of the values in the data array.

                 The second form of the function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    sumofsquares (263), sumsandsquares (264), totalvariance (266) , variance (266)


                 Listing:  mathex/ex44.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example44      ;


                 {  Program       to    d e m o n s t r a t et h e Sum    f u n c t i o n.  }


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    W r i t e l n(' Max   |_||_||_||_||_|:,|_|'MaxValue( E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Min   |_||_||_||_||_|:,|_|'MinValue( E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Sum   |_||_||_||_||_|:,|_|'Sum(E x A r r)a:y8 : 4 ) ;
                    W r i t e l n(' Sum  |_|(b ) |_|: |_|',Sum( @ExArray      [ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.45         sumofsquares

Declaration:      Function  sumofsquares(const  data  :    array  of  float)  :    float;  Function  sumofsquares(const
                 data  :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Sumofsquares returns the sum of the squares of the values in the data array.

                 The second form of the function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    sum (263), sumsandsquares (264), totalvariance (266) , variance (266)


                 Listing:  mathex/ex45.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example45      ;


                 {  Program       to    d e m o n s t r a t et h e SumOfSquares           f u n c t i o n.  }


                 Uses    math    ;
                                                                                 263

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    W r i t e l n(' Max   |_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'MaxValue(E x)A:r8r:a4y) ;
                    W r i t e l n(' Min   |_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'MinValue(E x)A:r8r:a4y) ;
                    W r i t e l n(' Sum  |_|s q u a r e s|_||_||_||_||_|:,|_|'SumOfSquares  (E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Sum  |_|s q u a r e|s_|(b) |_|: |_|',SumOfSquares       (@ExArray       [ 1 ] , 1 0 0 ) : 8 : 4*
 * ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.46         sumsandsquares

Declaration:      Procedure  sumsandsquares(const  data  :    array  of  float;  var  sum,sumofsquares  :
                 float);  Procedure  sumsandsquares(const  data  :    PFloat;  Const  N  :  Integer;  var
                 sum,sumofsquares  :    float);

Description:      sumsandsquares calculates the sum of the values and the sum of the squares of the values
                 in the data array and returns the results in sum and sumofsquares.

                 The second form of the function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    sum (263), sumofsquares (263), totalvariance (266) , variance (266)


                 Listing:  mathex/ex46.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example45      ;


                 {  Program       to    d e m o n s t r a t et h e SumOfSquares           f u n c t i o n.  }


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;
                    s , s s  :   f l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    W r i t e l n(' Max   |_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'MaxValue(E x)A:r8r:a4y) ;
                    W r i t e l n(' Min   |_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'MinValue(E x)A:r8r:a4y) ;
                    SumsAndSquares           (E x A r r a y,S , SS ) ;
                    W r i t e l n(' Sum   |_||_||_||_||_||_||_||_||_||_||_||_||_|:,|_|'S: 8 : 4 ) ;
                    W r i t e l n(' Sum  |_|s q u a r e s|_||_||_||_||_|:,|_|'SS: 8 : 4 ) ;
                    SumsAndSquares           (@ExArray       [ 1 ] , 1 0 0S,, SS ) ;



                                                                                 264

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    W r i t e l n(' Sum  |_|(b ) |_||_||_||_||_||_||_||_||_|:,|_|'S: 8 : 4 ) ;
                    W r i t e l n(' Sum  |_|s q u a r e|s_|(b) |_|: |_|',SS: 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.47         tan

Declaration:      Function  tan(x  :    float)  :    float;

Description:      Tan returns the tangent of  x.

       Errors:    If  x (normalized) is pi/2 or 3pi/2 then an overflow will occur.

     See also:    tanh (265), arcsin (240), sincos (261), arccos (239)


                 Listing:  mathex/ex47.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example47      ;


                 {  Program       to    d e m o n s t r a t et h e Tan    f u n c t i o n.  }


                 Uses    math    ;


                 Procedure        DoTan    ( A n g l e :   F l o a t) ;


                 b e g i n
                    Write    ( 'A n g l e |_|: |_|',RadToDeg    ( A n g l e) : 8 : 6 ) ;
                    W r i t e l n(' |_|Tangent    |_|: |_|',Tan ( A n g l e) : 8 : 6 ) ;
                 end  ;


                 b e g i n
                    DoTan    ( 0 ) ;
                    DoTan    ( Pi ) ;
                    DoTan    ( Pi / 3 ) ;
                    DoTAn    ( Pi / 4 ) ;
                    DoTan    ( Pi / 6 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.48         tanh

Declaration:      Function  tanh(x  :    float)  :    float;

Description:      Tanh returns the hyperbolic tangent of  x.

       Errors:    None.

     See also:    arcsin (240), sincos (261), arccos (239)


                 Listing:  mathex/ex48.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example48      ;


                 {  Program       to    d e m o n s t r a t et h e Tanh     f u n c t i o n.  }


                 Uses    math    ;


                 b e g i n



                                                                                 265

                 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    w r i t e l n(t a n h( 0 ) ) ;
                    w r i t e l n(t a n h( 1 ) ) ;
                    w r i t e l n(t a n h( - 1 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.49         totalvariance

Declaration:      Function  totalvariance(const  data  :    array  of  float)  :    float;  Function  totalvariance(const
                 data  :    PFloat;  Const  N  :  Integer)  :    float;

Description:      TotalVariance returns the total variance of the values in the data array.  It returns zero
                 if there is only one value.

                 The second form of the function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    variance (266), stddev (262), mean (252)


                 Listing:  mathex/ex49.pp

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example49      ;


                 {  Program       to    d e m o n s t r a t et h e T o t a l V a r i a n c ef u n c t i o n.  }


                 Uses    math    ;


                 Type
                    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


                 Var
                    I   :  I n t e g e r;
                    E x A r r a y :   TExArray      ;
                    TV   :   f l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I :=1    to   1 0 0  do
                        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
                    TV  := T o t a l V a r i a n c(eE x A r r a y) ;
                    W r i t e l n(' T o t a l|_|v a r i a n c|e_||_||_||_||_|:,|_|'TV: 8 : 4 ) ;
                    TV  := T o t a l V a r i a n c(e@ExArray      [ 1 ] , 1 0 0 ) ;
                    W r i t e l n(' T o t a l|_|V a r i a n c|e_|(b) |_|: |_|',TV: 8 : 4 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 12.3.50         variance

Declaration:      Function  variance(const  data  :    array  of  float)  :    float;  Function  variance(const
                 data  :    PFloat;  Const  N  :  Integer)  :    float;

Description:      Variance returns the variance of the values in the data array.  It returns zero if there is
                 only one value.

                 The second form of the function accepts a pointer to an array of  N values.

       Errors:    None.

     See also:    totalvariance (266), stddev (262), mean (252)



                                                                                 266

 __________________________________________________________________________12.3.___FUNCTIONS_AND_PROCEDURES________________________*
 *____
 Listing:  mathex/ex50.pp

________________________________________________________________________________________________________________________________
 Program       Example50      ;


 {  Program       to    d e m o n s t r a t et h e V a r i a n c e f u n c t i o n.  }


 Uses    math    ;


 Type
    TExArray       =   Array    [ 1 . . 1 0 0 ] of   F l o a t;


 Var
    I   :  I n t e g e r;
    E x A r r a y :   TExArray      ;
    V   :  f l o a t;


 b e g i n
    Randomize       ;
    f o r  I :=1    to   1 0 0  do
        E x A r r a y[i ] : = (Random   - Random     ) * 1 0 0 ;
    V :=  V a r i a n c(eE x A r r a y) ;
    W r i t e l n(' V a r i a n c e|_||_||_||_||_|:,|_|'V: 8 : 4 ) ;
    V :=  V a r i a n c(e@ExArray      [ 1 ] , 1 0 0 ) ;
    W r i t e l n(' V a r i a n c e|_|(b) |_|: |_|',V: 8 : 4 ) ;
_end__._________________________________________________________________________________________________________________________

                                                                 267


Chapter   13


The   MMX   unit



This chapter describes the MMX unit.  This unit allows you to use the MMX capabilities of the
Free Pascal compiler.  It was written by Florian Kl"ampfl for the I386 processor.  It should
work on all platforms that use the Intel processor.
13.1          Variables,  Types  and  constants


The following types are defined in the MMX unit:


tmmxshortint  =  array[0..7]  of  shortint;
tmmxbyte  =  array[0..7]  of  byte;
tmmxword  =  array[0..3]  of  word;
tmmxinteger  =  array[0..3]  of  integer;
tmmxfixed  =  array[0..3]  of  fixed16;
tmmxlongint  =  array[0..1]  of  longint;
tmmxcardinal  =  array[0..1]  of  cardinal;
{  for  the  AMD  3D  }
tmmxsingle  =  array[0..1]  of  single;


And the following pointers to the above types:


pmmxshortint  =  ^tmmxshortint;
pmmxbyte  =  ^tmmxbyte;
pmmxword  =  ^tmmxword;
pmmxinteger  =  ^tmmxinteger;
pmmxfixed  =  ^tmmxfixed;
pmmxlongint  =  ^tmmxlongint;
pmmxcardinal  =  ^tmmxcardinal;
{  for  the  AMD  3D  }
pmmxsingle  =  ^tmmxsingle;


The following initialized constants allow you to determine if the computer has MMX extensions.
They are set correctly in the unit's initialization code.


is_mmx_cpu  :  boolean  =  false;
is_amd_3d_cpu  :  boolean  =  false;


                                                            268

                 __________________________________________________________________________13.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 13.2          Functions  and  Procedures



                 13.2.1        Emms

Declaration:      Procedure  Emms  ;

Description:      Emms sets all floating point registers to empty.  This procedure must be called after you have
                 used any MMX instructions, if you want to use floating point arithmetic.  If you just want to
                 move floating point data around, it isn't necessary to call this function, the compiler doesn't
                 use the FPU registers when moving data.  Only when doing calculations, you should use this
                 function.

       Errors:    None.

     See also:    Programmers' guide


   Example::      Program  MMXDemo;
                 uses  mmx;
                 var
                     d1  :  double;
                     a  :  array[0..10000]  of  double;
                     i  :  longint;
                 begin
                     d1:=1.0;
                 {$mmx+}
                     {  floating  point  data  is  used,  but  we  do  _no_  arithmetic  }
                     for  i:=0  to  10000  do
                         a[i]:=d2;    {  this  is  done  with  64  bit  moves  }
                 {$mmx-}
                     emms;     {  clear  fpu  }
                     {  now  we  can  do  floating  point  arithmetic  again  }
                 end.



                                                                                 269


Chapter   14


The   MsMouse   unit



The msmouse unit provides basic mouse handling under dos (Go32v1 and Go32v2) Some
general remarks about the msmouse unit:


    o  The mouse driver does not know when the text screen scrolls.  This results in unerased
       mouse cursors on the screen when the screen scrolls while the mouse cursor is visible.
       The solution is to hide the mouse cursor (using HideMouse) when you write something
       to the screen and to show it again afterwards (using ShowMouse).

    o  All Functions/Procedures that return and/or accept coordinates of the mouse cursor,
       always do so in pixels and zero based (so the upper left corner of the screen is (0,0)).
       To get the (column, row) in standard text mode, divide both x and y by 8 (and add 1
       if you want to have it 1 based).

    o  The real resolution of graphic modes and the one the mouse driver uses can differ.  For
       example, mode 13h (320*200 pixels) is handled by the mouse driver as 640*200, so you
       will have to multiply the X coordinates you give to the driver and divide the ones you
       get from it by 2 in that mode.

    o  By default the msmouse unit is compiled with the conditional define MouseCheck.  This
       causes every procedure/function of the unit to check the MouseFound variable prior to
       doing anything.  Of course this is not necessary, so if you are sure you are not calling
       any mouse unit procedures when no mouse is found, you can recompile the mouse unit
       without this conditional define.

    o  You will notice that several procedures/functions have longint sized parameters while
       only the lower 16 bits are used.  This is because FPC is a 32 bit compiler and conse-
       quently 32 bit parameters result in faster code.
14.1          Constants,  types  and  variables


The following constants are defined (to be used in e.g.  the GetLastButtonPress (271) call).


 LButton  =  1;  {left  button}
 RButton  =  2;  {right  button}
 MButton  =  4;  {middle  button}


The following variable exist:


   MouseFound:  Boolean;



                                                            270

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 it is set to True or False in the unit's initialization code.
                 14.2          Functions  and  procedures



                 14.2.1        GetLastButtonPress

Declaration:      Function  GetLastButtonPress  (Button:    Longint;  Var  x,y:Longint)  :    Longint;

Description:      GetLastButtonPress  Stores  the  position  where  Button  was  last  pressed  in  x  and  y  and
                 returns the number of times this button has been pressed since the last call to this function
                 with  Button  as  parameter.   For  Button  you  can  use  the  LButton,  RButton  and  MButton
                 constants for resp.  the left, right and middle button.  With certain mouse drivers, checking
                 the middle button when using a two-button mouse to gives and clears the stats of the right
                 button.

       Errors:    None.

     See also:    GetLastButtonRelease (272)


                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r  G e t L a s t B u t t o n P r e sasnd   G e t L a s t B u t t o n R e l e a}s e


                 Uses    MsMouse      ,  C r t;


                 Var    x ,  y ,  t i m e s:  L o n g i n t;
                        c :  Char   ;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           C l r S c r;
                           ShowMouse       ;
                           W r i t e l n(' Move   |_|t h e|_|mouse |_|and |_|c l i c k|_|t h|e_|b u t t o n|s_|(p r e s|s_|e s c a|*
 *p_e|to|_|q u i)t. ') ;
                           W r i t e l n(' P r e s s|_|t h e|_|L-key |_|to|_|s e e|_|t h|e_|s t a t|s_|f o|r_|t h|e_|l e f|t_|b u t*
 * t o.n') ;
                           W r i t e l n(' P r e s s|_|t h e|_|R-key |_|to|_|s e e|_|t h|e_|s t a t|s_|f o|r_|t h|e_|r i g h|t_|b u*
 * t t o.n') ;
                           W r i t e l n(' P r e s s|_|t h e|_|M-key |_|to|_|s e e|_|t h|e_|s t a t|s_|f o|r_|t h|e_|m i d d l|e_|b*
 * u t t.o'n) ;
                           GotoXY     ( 1 , 1 9 ) ;
                           Write    ( ' S i n c e|_|t h|e_|l a s|t_|c a l|l_|to|_|G e t L a s t B u t t o n P r|e_s|sw i|t_h|t h|i_*
 *s|b u t t o|n_|as|_|p a r a m e@
                           GotoXY     ( 1 , 2 2 ) ;
                           Write    ( ' S i n c e|_|t h|e_|l a s|t_|c a l|l_|to|_|G e t L a s t B u t t o n R e l e|a_s|ew i|t_h|t *
 *h|i_s|b u t t|o_n|as|_|p a r a @
                           Repeat
                               I f  Keypressed         Then
                                  Begin
                                      c  : =  UpCase     ( Readkey     ) ;
                                      Case    c   Of
                                         ' L ':
                                             Begin
                                                GotoXY     ( 1 ,  2 0 ) ;
                                                C l r E o l;
                                                t i m e s : =   G e t L a s t B u t t o n P r e(sLsButton    ,   x ,  y ) ;
                                                Write    ( ' l e f t|_|b u t t o|n_|has|_|been |_|p r e s s e|d_|',t i m e s,
                                                              ' |_|t i m e,s|_|t h e|_|l a s|t_|t i m|e_|a|t_|(,'x, ' , ', y , ' ) *
 *') ;
                                                t i m e s : =   G e t L a s t B u t t o n R e l e a(sLeButton    ,  x ,  y ) ;
                                                GotoXY     ( 1 , 2 3 ) ;
                                                C l r E o l;
                                                Write    ( ' l e f t|_|b u t t o|n_|has|_|been |_|r e l e a s e|d_|',t i m e s,
                                                              ' |_|t i m e,s|_|t h e|_|l a s|t_|t i m|e_|a|t_|(,'x, ' , ', y , ' ) *
 *')



                                                                                 271

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                                            End   ;
                                         ' R ':
                                             Begin
                                                GotoXY     ( 1 ,  2 0 ) ;
                                                C l r E o l;
                                                t i m e s : =   G e t L a s t B u t t o n P r e(sRsButton    ,   x ,  y ) ;
                                                W r i t e l n(' r i g h t|_|b u t t o|n_|has|_|been  |_|p r e s s e|d_|',t i m e,s
                                                              ' |_|t i m e,s|_|t h e|_|l a s|t_|t i m|e_|a|t_|(,'x, ' , ', y , ' ) *
 *') ;
                                                t i m e s : =   G e t L a s t B u t t o n R e l e a(sReButton    ,  x ,  y ) ;
                                                GotoXY     ( 1 , 2 3 ) ;
                                                C l r E o l;
                                                Write    ( ' r i g h t|_|b u t t o|n_|has|_|been |_|r e l e a s e|d_|',t i m e s,
                                                              ' |_|t i m e,s|_|t h e|_|l a s|t_|t i m|e_|a|t_|(,'x, ' , ', y , ' ) *
 *')
                                            End   ;
                                         'M  ':
                                             Begin
                                                GotoXY     ( 1 ,  2 0 ) ;
                                                C l r E o l;
                                                t i m e s : =   G e t L a s t B u t t o n P r e(sMsButton    ,   x ,  y ) ;
                                                W r i t e l n(' m i d d l e|_|b u t t o|n_|has|_|been |_|p r e s s e|d_|',t i m e s,
                                                              ' |_|t i m e,s|_|t h e|_|l a s|t_|t i m|e_|a|t_|(,'x, ' , ', y , ' ) *
 *') ;
                                                t i m e s : =   G e t L a s t B u t t o n R e l e a(sMeButton    ,  x ,  y ) ;
                                                GotoXY     ( 1 , 2 3 ) ;
                                                C l r E o l;
                                                Write    ( 'm i d d l e|_|b u t t o|n_|has|_|been  |_|r e l e a s e|d_|',t i m e,s
                                                              ' |_|t i m e,s|_|t h e|_|l a s|t_|t i m|e_|a|t_|(,'x, ' , ', y , ' ) *
 *')
                                            End
                                     End
                                  End  ;
                           U n t i l ( c  =  # 2 7 ) ;   { e s c a p e}
                           While      KeyPressed         do   ReadKey     ;
                           GotoXY     ( 1 , 2 4 ) ;
                           HideMouse
                        End
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 14.2.2        GetLastButtonRelease

Declaration:      Function  GetLastButtonRelease  (Button:    Longint;  Var  x,y:Longint)  :    Longint;

Description:      GetLastButtonRelease stores the position where Button was last released in x and y and
                 returns the number of times this button has been released since the last call to this function
                 with  Button  as  parameter.   For  button  you  can  use  the  LButton,  RButton  and  MButton
                 constants for resp.  the left, right and middle button.  With certain mouse drivers, checking
                 the middle button when using a two-button mouse to gives and clears the stats of the right
                 button.

       Errors:    None.

     See also:    GetLastButtonPress (271)


                 For an example, see GetLastButtonPress (271).
                 14.2.3        GetMouseState

Declaration:      Procedure  GetMouseState  (Var  x,  y,  buttons:    Longint);
                                                                                 272

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      GetMouseState Returns information on the current mouse position and which buttons are
                 currently  pressed.   x  and  y  return  the  mouse  cursor  coordinates  in  pixels.   Buttons  is  a
                 bitmask.  Check the example program to see how you can get the necessary information from
                 it.

       Errors:    None.

     See also:    LPressed (275), MPressed (275), RPressed (275), SetMousePos (276)


                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r G e t M o u s e S t a t,e  I s L P r e s s e,d  I s R P r e s s e dand    I s M P r e s s e}d


                 Uses    MsMouse      ,  C r t;


                 Var   X  ,  Y ,  S t a t e:  L o n g i n t;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           C l r S c r;
                           ShowMouse       ;
                           GotoXY     ( 5 , 2 4 ) ;
                           Write    ( ' L e f t|_|b u t t o:n') ;
                           GotoXY     ( 3 0 , 2 4 ) ;
                           Write    ( 'R i g h t|_|b u t t o n: ') ;
                           GotoXY     ( 5 5 , 2 4 ) ;
                           Write    ( 'M i d d l e|_|b u t t o:n' ) ;
                           While      KeyPressed         do   Readkey     ;   { c l e a r k e y b o a r d b u f f e r}
                           Repeat
                                G e t M o u s e S t a t(ex ,  y ,  S t a t e) ;
                                GotoXY     ( 2 0 ,  2 2 ) ;
                                Write    ( 'X  : |_|',x: 5 , ' |_|(column   : |_|', (x  d i v  8 ) : 2 ,' ) |_||_|Y: |_|',y: 5 ,' |*
 *_|(row  : |_|', (y  d i v  8 ) @
                                GotoXY     ( 1 8 ,  2 4 ) ; { l e f t  b u t t o n}
                                 I f (  S t a t e and    LButton     )  =   LButton       Then
                 { o r:  " I f   L P r e s s e dThen   " .   I f  you    u s e  t h i s f u n c t i o n,  no   c a l l  to   G e t *
 *M o u s e S t a t e
                   i s  n e c e s s a r}y
                                    Write    (' Down   ' )
                                 E l s e
                                    Write    (' Up  |_||_|') ;
                                GotoXY     ( 4 4 ,  2 4 ) ; { r i g h t  b u t t o n}
                                 I f (  S t a t e and    RButton     )  =   RButton       Then
                 { o r:  " I f   R P r e s s e dThen   "}
                                    Write    (' Down   ' )
                                 E l s e
                                    Write    (' Up  |_||_|') ;
                                GotoXY     ( 7 0 ,  2 4 ) ; { m i d d l e b u t t o n}
                                 I f (  S t a t e and    MButton     )  =   MButton       Then
                 { o r:  " I f  MPressed        Then   "}
                                    Write    (' Down   ' )
                                 E l s e
                                    Write    (' Up  |_||_|')
                           U n t i l  KeyPressed       ;
                           HideMouse       ;
                           While      KeyPressed         Do   Readkey
                        End
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 273

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 14.2.4        HideMouse

Declaration:      Procedure  HideMouse  ;

Description:      HideMouse makes the mouse cursor invisible.  Multiple calls to HideMouse will require just
                 as many calls to ShowMouse to make the mouse cursor visible again.

       Errors:    None.

     See also:    ShowMouse (280), SetMouseHideWindow (276)


                 For an example, see ShowMouse (280).
                 14.2.5        InitMouse

Declaration:      Procedure  InitMouse  ;

Description:      InitMouse Initializes the mouse driver sets the variable MouseFound depending on whether
                 or  not  a  mouse  is  found.  This  is  Automatically  called  at  the  start  of  your  program.  You
                 should never have to call it, unless you want to reset everything to its default values.

       Errors:    None.

     See also:    MouseFound variable.


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Mouse1    ;


                 { e x a m p l e f o r  I n i t M o u s eand    MouseFound       }


                 Uses    MsMouse      ;


                 Begin
                    I f  MouseFound         Then
                        Begin
                         { go    i n t o g r a p h i c s mode    1 3 h }
                           Asm
                               movl    $0x013     ,  % eax
                               p u s h l%  ebp
                               i n t  $0x010
                               p o p l%  ebp
                           End   ;
                           I n i t M o u s e;
                           ShowMouse       ;  { o t h e r w i s e i t  s t a y s  i n v i s i b l}e
                           W r i t e l n(' Mouse    |_|Found  ! |_|(p r e s s|_|e n t e|r_|to|_|q u i)t') ;
                           Readln     ;
                         { back     to   t e x t  mode   }
                           Asm
                               movl    $3  ,  % eax
                               p u s h l%  ebp
                               i n t  $0x010
                               p o p l%  ebp
                           End
                        End
                _End__.____________________________________________________________________________________________________________*
 *_____________

                                                                                 274

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 14.2.6        LPressed

Declaration:      Function  LPressed  :    Boolean;

Description:      LPressed returns True if the left mouse button is pressed.  This is simply a wrapper for
                 the GetMouseState procedure.

       Errors:    None.

     See also:    GetMouseState (272), MPressed (275), RPressed (275)


                 For an example, see GetMouseState (272).
                 14.2.7        MPressed

Declaration:      Function  MPressed  :    Boolean;

Description:      MPressed returns True if the middle mouse button is pressed.  This is simply a wrapper for
                 the GetMouseState procedure.

       Errors:    None.

     See also:    GetMouseState (272), LPressed (275), RPressed (275)


                 For an example, see GetMouseState (272).
                 14.2.8        RPressed

Declaration:      Function  RPressed  :    Boolean;

Description:      RPressed returns True if the right mouse button is pressed.  This is simply a wrapper for
                 the GetMouseState procedure.

       Errors:    None.

     See also:    GetMouseState (272), LPressed (275), MPressed (275)


                 For an example, see GetMouseState (272).
                 14.2.9        SetMouseAscii

Declaration:      Procedure  SetMouseAscii  (Ascii:    Byte);

Description:      SetMouseAscii sets the Ascii value of the character that depicts the mouse cursor in text
                 mode.  The difference between this one and SetMouseShape (277), is that the foreground and
                 background colors stay the same and that the Ascii code you enter is the character that you
                 will get on screen; there's no XOR'ing.

       Errors:    None

     See also:    SetMouseShape (277)

                                                                                 275

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r  S e t M o u s e A s c i}i


                 { w a r n i n g: no    e r r o r c h e c k i n g i s  p e r f o r m e don   t h e   i n p u t}


                 Uses    MsMouse      ,  C r t;


                 Var    a s c i i:  Byte   ;
                        x ,y :   L o n g i n t;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           C l r S c r;
                           W r i t e l n(' P r e s s|_|any |_|mouse  |_|b u t t o|n_|to|_|q u i|t_|a f t e|r_|you'' ve  |_|e n t e *
 *r e|d_|an|_|A s c i|i_|v a l u.@
                           W r i t e l n;
                           W r i t e l n(' ASCII    |_|v a l u|e_|o|f_|mouse  |_|c u r s o:r' ) ;
                           ShowMouse       ;
                           Repeat
                              GotoXY     ( 3 0 , 3 ) ;
                               C l r E o l;
                               Readln    ( a s c i i) ;
                               S e t M o u s e A s c i(ia s c i i)
                           U n t i l (  G e t L a s t B u t t o n P r e(sLsButton    ,x , y )  < >  0 )  Or
                                      ( G e t L a s t B u t t o n P r e(sRsButton    ,x , y )  < >  0 )  Or
                                      ( G e t L a s t B u t t o n P r e(sMsButton    ,x , y )  < >  0 ) ;
                           HideMouse
                        End  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 14.2.10         SetMouseHideWindow

Declaration:      Procedure  SetMouseHideWindow  (xmin,ymin,xmax,ymax:    Longint);

Description:      SetMouseHideWindow defines a rectangle on screen with top-left corner at (xmin,ymin) and
                 botto-right corner at (xmax,ymax),which causes the mouse cursor to be turned off when it
                 is moved into it.  When the mouse is moved into the specified region, it is turned off until
                 you  call  ShowMouse  again.   However,  once  you've  called  ShowMouse  (280),  you'll  have  to
                 call SetMouseHideWindow again to redefine the hide window...  This may be annoying, but
                 it's the way it's implemented in the mouse driver.  While xmin,  ymin,  xmax and ymax are
                 Longint parameters, only the lower 16 bits are used.

                 Warning:  it seems Win98 SE doesn't (properly) support this function, maybe this already
                 the case with earlier versions too!

       Errors:    None.

     See also:    ShowMouse (280), HideMouse (274)


                 nputlistingmouseex/mouse9.pp
                 14.2.11         SetMousePos

Declaration:      Procedure  SetMousePos  (x,y:Longint);

Description:      SetMosusePos  sets  the  position  of  the  mouse  cursor  on  the  screen.   x  is  the  horizontal
                 position in pixels, y the vertical position in pixels.  The upper-left hand corner of the screen
                 is the origin.  While x and y are longints, only the lower 16 bits are used.



                                                                                 276

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
       Errors:    None.

     See also:    GetMouseState (272)


                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r SetMousePos        }


                 Uses    MsMouse      ,  C r t;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           ShowMouse       ;
                           While      KeyPressed         do   ReadKey     ;
                           Repeat
                               SetMousePos        (Random     ( 8 0 * 8 ) , Random     ( 2 5 * 8 ) ) ;
                               d e l a y( 1 0 0 ) ;
                           U n t i l  Keypressed       ;
                           HideMouse       ;
                           While      KeyPressed         do   ReadKey     ;
                        End  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 14.2.12         SetMouseShape

Declaration:      Procedure  SetMouseShape  (ForeColor,BackColor,Ascii:    Byte);

Description:      SetMouseShape defines how the mouse cursor looks in textmode The character and its at-
                 tributes that are on the mouse cursor's position on screen are XOR'ed with resp.  ForeColor,
                 BackColor and Ascii.  Set them all to 0 for a "transparent" cursor.

       Errors:    None.

     See also:    SetMouseAscii (275)


                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r SetMouseShape          }


                 { w a r n i n g: no    e r r o r c h e c k i n g i s  p e r f o r m e don   t h e   i n p u t}


                 { t h e  A s c i i v a l u e you     e n t e r i s  XOR  ' ed   w i t h  t h e  A s c i i  v a l u e o f  t h e  c*
 * h a r a c t e r
                  on    t h e  s c r e e n o v e r  which     you    move     t h e  c u r s o r. To    g e t  a  " t r a n s p a r*
 * e n"t  c u r s o r,
                   u s e  t h e  A s c i i v a l u e 0 }


                 Uses    MsMouse      ,  C r t;


                 Var    a s c i i,  f c ,  bc  :  Byte   ;
                        x ,y :   L o n g i n t;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           C l r S c r;
                           W r i t e l n(' P r e s s|_|any |_|mouse  |_|b u t t o|n_|to|_|q u i|t_|a f t e|r_|you'' ve  |_|e n t e *
 *r e|d_|a|_|s e q u e n|c_e|o|f_@
                           W r i t e l n;
                           W r i t e l n(' ASCII    |_|v a l u|e_|o|f_|mouse  |_|c u r s o:r' ) ;
                           W r i t e l n(' F o r g r o u n d|_|c o l o:r') ;
                           W r i t e l n(' Background       |_|c o l o r: ') ;



                                                                                 277

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                           ShowMouse       ;
                           Repeat
                              GotoXY     ( 3 0 , 3 ) ;
                               C l r E o l;
                               Readln    ( a s c i i) ;
                              GotoXY     ( 1 8 , 4 ) ;
                               C l r E o l;
                               Readln    ( f c ) ;
                              GotoXY     ( 1 9 , 5 ) ;
                               C l r E o l;
                               Readln    ( bc  ) ;
                               SetMouseShape         ( f c ,  bc  ,  a s c i i)
                           U n t i l (  G e t L a s t B u t t o n P r e(sLsButton    ,x , y )  < >  0 )  Or
                                      ( G e t L a s t B u t t o n P r e(sRsButton    ,x , y )  < >  0 )  Or
                                      ( G e t L a s t B u t t o n P r e(sMsButton    ,x , y )  < >  0 ) ;
                           HideMouse
                        End  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 14.2.13         SetMouseSpeed

Declaration:      Procedure  SetMouseSpeed  (Horizontal,  Vertical:    Longint);

Description:      SetMouseSpeed  sets  the  mouse  speed  in  mickeys  per  8  pixels.   A  mickey  is  the  smallest
                 measurement unit handled by a mouse.  With this procedure you can set how many mickeys
                 the mouse should move to move the cursor 8 pixels horizontally of vertically.  The default
                 values are 8 for horizontal and 16 for vertical movement.  While this procedure accepts longint
                 parameters, only the low 16 bits are actually used.

       Errors:    None.

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Uses    MsMouse      ,  C r t;


                 Var    h o r,   v e r t:  L o n g i n t;
                        x ,  y :  L o n g i n t;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           C l r S c r;
                           W r i t e l n(' C l i c k|_|any |_|b u t t o|n_|to|_|q u i|t_|a f t e|r_|you'' ve |_|e n t e r e|d_|a|_|*
 *s e q u e n|c_e|o|f_|numbers   @
                           W r i t e l n;
                           W r i t e l n(' H o r i z o n t a|l_|m i c k e'y's |_|p e r|_|p i x e:l') ;
                           W r i t e l n(' V e r t i c a l|_|m i c k e'y's|_|p e r|_|p i x e:l') ;
                           ShowMouse       ;
                           Repeat
                              GotoXY     ( 3 2 , 3 ) ;
                               C l r E o l;
                               Readln    ( h o r) ;
                              GotoXY     ( 3 0 , 4 ) ;
                               C l r E o l;
                               Readln    ( v e r t) ;
                               SetMouseSpeed         ( h o r ,  v e r t) ;
                           U n t i l (  G e t L a s t B u t t o n P r e(sLsButton    ,x , y )  < >  0 )  Or
                                      ( G e t L a s t B u t t o n P r e(sRsButton    ,x , y )  < >  0 )  Or



                                                                                 278

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                                      ( G e t L a s t B u t t o n P r e(sMsButton    ,x , y )  < >  0 ) ;
                        End
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 14.2.14         SetMouseWindow

Declaration:      Procedure  SetMouseWindow  (xmin,ymin,xmax,ymax:    Longint);

Description:      SetMousWindow  defines  a  rectangle  on  screen  with  top-left  corner  at  (xmin,ymin)  and
                 bottom-right  corner  at  (xmax,ymax),  out  of  which  the  mouse  cursor  can't  move.   This
                 procedure  is  simply  a  wrapper  for  the  SetMouseXRange  (279)  and  SetMouseYRange  (280)
                 procedures.  While xmin,  ymin,  xmax and ymax are Longint parameters, only the lower 16
                 bits are used.

       Errors:    None.

     See also:    SetMouseXRange (279), SetMouseYRange (280)


                 For an example, see SetMouseXRange (279).
                 14.2.15         SetMouseXRange

Declaration:      Procedure  SetMouseXRange  (Min,  Max:    Longint);

Description:      SetMouseXRange  sets  the  minimum  (Min)  and  maximum  (Max)  horizontal  coordinates  in
                 between which the mouse cursor can move.  While Min and Max are Longint parameters, only
                 the lower 16 bits are used.

       Errors:    None.

     See also:    SetMouseYRange (280), SetMouseWindow (279)


                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r SetMouseXRange           ,  SetMouseYRange            and    SetMouseWindow           }


                 Uses    MsMouse      ,  C r t;


                 Begin
                    I f  MouseFound         Then
                        Begin
                           SetMouseXRange           ( 2 0 * 8 , 5 0 * 8 ) ; { c h a r r a c t e rw i d t h and     h e i g h t=  8 *
 *   p i x e l s}
                           SetMouseYRange           ( 1 0 * 8 , 1 5 * 8 ) ;


                 { t h e two     l i n e s o f  code     have     e x a c t l y t h e same     e f f e c t as
                  SetMouseWindow           ( 2 0 * 8 , 1 0 * 8 , 5 0 * 8 , 1 5 * 8 ) }


                           W r i t e l n(' P r e s s|_|any |_|key |_|to|_|q u i t. ') ;
                           ShowMouse       ;
                           While      KeyPressed         Do   ReadKey     ;
                           Readkey     ;
                           While      KeyPressed         Do   ReadKey     ;
                           HideMouse
                        End
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 279

                 __________________________________________________________________________14.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 14.2.16         SetMouseYRange

Declaration:      Procedure  SetMouseYRange  (Min,  Max:    Longint);

Description:      SetMouseYRange sets the minimum (Min) and maximum (Max) vertical coordinates in be-
                 tween which the mouse cursor can move.  While Min and Max are Longint parameters, only
                 the lower 16 bits are used.

       Errors:    None.

     See also:    SetMouseXRange (279), SetMouseWindow (279)


                 For an example, see SetMouseXRange (279).
                 14.2.17         ShowMouse

Declaration:      Procedure  ShowMouse  ;

Description:      ShowMouse makes the mouse cursor visible.  At the start of your progam, the mouse cursor
                 is invisible.

       Errors:    None.

     See also:    HideMouse (274),SetMouseHideWindow (276)


                ___________________________________________________________________________________________________________________*
 *_____________
                 { e x a m p l e f o r ShowMouse         and    HideMouse      }


                 Uses    MsMouse      ;


                 Begin
                    C l r S c r;
                    I f  MouseFound         Then
                        Begin
                           W r i t e l n(' Now  |_|you |_|can |_|s e e|_|t h|e_|mouse  . . . |_|(p r e s|s_|e n t e|r_|to|_|c o n t*
 * i n)u'e) ;
                           ShowMouse       ;
                           Readln     ;
                           HideMouse       ;
                           W r i t e l n(' And  |_|now |_|you |_|can ' ' t . . . |_|(p r e s|s_|e n t e|r_|to|_|q u i)t') ;
                           Readln
                        End
                _End__.____________________________________________________________________________________________________________*
 *_____________


                                                                                 280


Chapter   15


The   Ob jects   unit.



This chapter documents the objects unit.  The unit was implemented by many people, and
was mainly taken from the FreeVision sources.  It has been ported to all supported platforms.

The methods and fields that are in a Private part of an object declaration have been left
out of this documentation.
15.1          Constants


The following constants are error codes, returned by the various stream objects.


CONST
    stOk               =    0;  {  No  stream  error  }
    stError          =  -1;  {  Access  error  }
    stInitError    =  -2;  {  Initialize  error  }
    stReadError    =  -3;  {  Stream  read  error  }
    stWriteError  =  -4;  {  Stream  write  error  }
    stGetError     =  -5;  {  Get  object  error  }
    stPutError     =  -6;  {  Put  object  error  }
    stSeekError    =  -7;  {  Seek  error  in  stream  }
    stOpenError    =  -8;  {  Error  opening  stream  }


These constants can be passed to constructors of file streams:


CONST
    stCreate       =  $3C00;  {  Create  new  file  }
    stOpenRead    =  $3D00;  {  Read  access  only  }
    stOpenWrite  =  $3D01;  {  Write  access  only  }
    stOpen          =  $3D02;  {  Read/write  access  }


The following constants are error codes, returned by the collection list objects:


CONST
    coIndexError  =  -1;  {  Index  out  of  range  }
    coOverflow     =  -2;  {  Overflow  }


Maximum data sizes (used in determining how many data can be used.

                                                            281

_________________________________________________________________________________________________________________15.2.___TYPES_____*
 *___
CONST
    MaxBytes  =  128*1024*1024;                                           {  Maximum  data  size  }
    MaxWords  =  MaxBytes  DIV  SizeOf(Word);                       {  Max  word  data  size  }
    MaxPtrs  =  MaxBytes  DIV  SizeOf(Pointer);                    {  Max  ptr  data  size  }
    MaxCollectionSize  =  MaxBytes  DIV  SizeOf(Pointer);    {  Max  collection  size  }
15.2          Types


The follwing auxiliary types are defined:


TYPE
    {  Character  set  }
    TCharSet  =  SET  Of  Char;
    PCharSet  =  ^TCharSet;


    {  Byte  array  }
    TByteArray  =  ARRAY  [0..MaxBytes-1]  Of  Byte;
    PByteArray  =  ^TByteArray;


    {  Word  array  }
    TWordArray  =  ARRAY  [0..MaxWords-1]  Of  Word;
    PWordArray  =  ^TWordArray;


    {  Pointer  array  }
    TPointerArray  =  Array  [0..MaxPtrs-1]  Of  Pointer;
    PPointerArray  =  ^TPointerArray;


    {  String  pointer  }
    PString  =  ^String;


    {  Filename  array  }
    AsciiZ  =  Array  [0..255]  Of  Char;


    Sw_Word       =  Cardinal;
    Sw_Integer  =  LongInt;


The following records are used internaly for easy type conversion:


TYPE
    {  Word  to  bytes}
    WordRec  =  packed  RECORD
        Lo,  Hi:  Byte;
    END;


    {  LongInt  to  words  }
    LongRec  =  packed  RECORD
        Lo,  Hi:  Word;
    END;


   {  Pointer  to  words  }
    PtrRec  =  packed  RECORD
        Ofs,  Seg:  Word;
    END;



                                                                282

                 __________________________________________________________________________15.3.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                 The following record is used when streaming objects:


                 TYPE
                     PStreamRec  =  ^TStreamRec;
                     TStreamRec  =  Packed  RECORD
                          ObjType:  Sw_Word;
                          VmtLink:  pointer;
                          Load  :  Pointer;
                          Store:  Pointer;
                          Next  :  PStreamRec;
                     END;


                 The TPoint basic object is used in the TRect object (see section 15.4, page 286):


                 TYPE
                     PPoint  =  ^TPoint;
                     TPoint  =  OBJECT
                          X,  Y:  Sw_Integer;
                     END;
                 15.3          Procedures  and  Functions



                 15.3.1        NewStr

Declaration:      Function  NewStr  (Const  S:  String):    PString;

Description:      NewStr makes a copy of the string S on the heap, and returns a pointer to this copy.

                 The allocated memory is not based on the declared size of the string passed to NewStr, but
                 is baed on the actual length of the string.

       Errors:    If not enough memory is available, an 'out of memory' error will occur.

     See also:    DisposeStr (284)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex40   ;


                 {  Program       to    d e m o n s t r a t et h e NewStr       f u n c t i o n}


                 Uses     O b j e c t s;


                 Var    S  :   S t r i n g;
                       P   :   P S t r i n g;


                 b e g i n
                    S :=  'Some   |_|r e a l l|y_|c u t|e_|s t r i n'g;
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                    P := NewStr     (S  ) ;
                    I f  P ^<>  S   then
                        W r i t e l n( ' Oh - oh  . . . |_|S o m e t h i n|g_|i|s_|wrong |_|! !)';
                    W r i t e l n ( ' A l l o c a t e|d_|s t r i n.g|_|Memavail    |_|: |_|',Memavail     ) ;
                    D i s p o s e S t r(P) ;
                    W r i t e l n ( ' D e a l l o c a t e|d_|s t r i n.g|_|Memavail    |_|: |_|',Memavail    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________

                                                                                 283

                 __________________________________________________________________________15.3.___PROCEDURES_AND_FUNCTIONS________*
 *____________________
                 15.3.2        DisposeStr

Declaration:      Procedure  DisposeStr  (P:  PString);

Description:      DisposeStr removes a dynamically allocated string from the heap.

       Errors:    None.

     See also:    NewStr (283)


                 For an example, see NewStr (283).
                 15.3.3        Abstract

Declaration:      Procedure  Abstract;

Description:      When implementing abstract methods, do not declare them as abstract.  Instead, define
                 them simply as virtual.  In the implementation of such abstract methods, call the Abstract
                 procedure.  This allows explicit control of what happens when an abstract method is called.

                 The current implementation of Abstract terminates the program with a run-time error 211.

       Errors:    None.

     See also:    Most abstract types.
                 15.3.4        RegisterObjects

Declaration:      Procedure  RegisterObjects;

Description:      RegisterObjects registers the following objects for streaming:

                     1.TCollection, see section 15.10, page 310.

                     2.TStringCollection, see section 15.12, page 329.

                     3.TStrCollection, see section 15.13, page 331.

       Errors:    None.

     See also:    RegisterType (284)
                 15.3.5        RegisterType

Declaration:      Procedure  RegisterType  (Var  S:  TStreamRec);

Description:      RegisterType registers a new type for streaming.  An object cannot be streamed unless it
                 has been registered first.  The stream record S needs to have the following fields set:


                 ObjType:  Sw___Word             This should be a unique identifier.  Each possible type should have
                       it's own identifier.

                 VmtLink:  pointer           This should contain a pointer to the VMT (Virtual Method Table) of
                       the object you try to register.  You can get it with the following expression:

                                VmtLink:  Ofs(TypeOf(MyType)^);

                 Load :  Pointer        is  a  pointer  to  a  method  that  initializes  an  instance  of  that  object,  and
                       reads the initial values from a stream.  This method should accept as it's sole argument
                       a PStream type variable.
                                                                                 284

          __________________________________________________________________________15.3.___PROCEDURES_AND_FUNCTIONS_______________*
 *_____________
          Store:  Pointer       is a pointer to a method that stores an instance of the object to a stream.
                This method should accept as it's sole argument a PStream type variable.


Errors:    In case of error (if a object with the same ObjType) is already registered), run-time error
          212 occurs.


         __________________________________________________________________________________________________________________________*
 *______
          Unit    MyObject      ;



          I n t e r f a c e


          Uses     O b j e c t s;


          Type
                  PMyObject        =  ^  TMyObject       ;
                  TMyObject        =   Object     ( TObject     )
                      F i e l d :   L o n g i n t;
                      C o n s t r u c t o rI n i t;
                      C o n s t r u c t o rLoad    ( Var    Stream      :   TStream     ) ;
                      D e s t r u c t o rDone   ;
                      Procedure        S t o r e  (Var     Stream      :  TStream      ) ;
                      F u n c t i o n   G e t F i e l d:   L o n g i n t;
                      Procedure         S e t F i e l d( V a l u e :   L o n g i n t) ;
                      end  ;


          I m p l e m e n t a t i o n


          C o n s t r u c t o rTMyobject      . I n i t;


          b e g i n
             I n h e r i t e d I n i t;
             F i e l d:=-1;
          end  ;


          C o n s t r u c t o rTMyobject      . Load     (Var     Stream      :  TStream      ) ;


          b e g i n
             Stream     .Read   ( F i e l d, S i z e o f(F i e l d) ) ;
          end  ;


          D e s t r u c t o rTMyObject       .Done   ;


          b e g i n
          end  ;


          F u n c t i o nTMyObject       . G e t F i e l d :  L o n g i n t;


          b e g i n
             G e t F i e l d:= F i e l d;
          end  ;


          Procedure        TMyObject       . S e t F i e l d( V a l u e :   L o n g i n t) ;


          b e g i n
             F i e l d:= V a l u e;
          end  ;

                                                                          285

                 _________________________________________________________________________________________________________________1*
 *5.4.___TRECT________
                 Procedure        TMyObject       . S t o r e ( Var    Stream      :  TStream      ) ;


                 b e g i n
                    Stream     .Write    ( F i e l d,S i z e O f( F i e l d) ) ;
                 end  ;


                 Const     MyObjectRec          :   TStreamRec        =  (
                               O b j t y p e :  6 6 6 ;
                               v m t l i n k :  Ofs  ( TypeOf     (TMyObject       ) ^ ) ;
                               Load    :   @TMyObject       . Load   ;
                               S t o r e :   @TMyObject       . S t o r e;
                               ) ;


                 b e g i n
                    R e g i s t e r O b j e c t;s
                    R e g i s t e r T y p e( MyObjectRec        ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.3.6        LongMul

Declaration:      Function  LongMul  (X,  Y:  Integer):    LongInt;

Description:      LongMul multiplies X with Y. The result is of type Longint.  This avoids possible overflow
                 errors you would normally get when multiplying X and Y that are too big.

       Errors:    None.

     See also:    LongDiv (286)
                 15.3.7        LongDiv

Declaration:      Function  LongDiv  (X:  Longint;  Y:  Integer):    Integer;

Description:      LongDiv  divides  X  by  Y.  The  result  is  of  type  Integer  instead  of  type  Longint,  as  you
                 would get normally.

       Errors:    If Y is zero, a run-time error will be generated.

     See also:    LongMul (286)
                 15.4          TRect


                 The TRect object is declared as follows:


                     TRect  =  OBJECT
                          A,  B:  TPoint;
                          FUNCTION  Empty:  Boolean;
                          FUNCTION  Equals  (R:  TRect):  Boolean;
                          FUNCTION  Contains  (P:  TPoint):  Boolean;
                          PROCEDURE  Copy  (R:  TRect);
                          PROCEDURE  Union  (R:  TRect);
                          PROCEDURE  Intersect  (R:  TRect);
                          PROCEDURE  Move  (ADX,  ADY:  Sw_Integer);
                          PROCEDURE  Grow  (ADX,  ADY:  Sw_Integer);
                          PROCEDURE  Assign  (XA,  YA,  XB,  YB:  Sw_Integer);
                     END;



                                                                                 286

                 _________________________________________________________________________________________________________________1*
 *5.4.___TRECT________
                 15.4.1        TRect.Empty

Declaration:      Function  TRect.Empty:    Boolean;

Description:      Empty returns True if the rectangle defined by the corner points A, B has zero or negative
                 surface.

       Errors:    None.

     See also:    TRect.Equals (287), TRect.Contains (288)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex1  ;


                 {  Program       to    d e m o n s t r a t eTRect   . Empty     }


                 Uses     o b j e c t s;



                 Var    ARect    ,BRect      :  TRect    ;
                       P   :   TPoint    ;


                 b e g i n
                    With     ARect    .A   do
                        b e g i n
                       X  : = 1 0 ;
                       Y  : = 1 0 ;
                        end  ;
                    With     ARect    .B   do
                        b e g i n
                       X  : = 2 0 ;
                       Y  : = 2 0 ;
                        end  ;
                    {   O f f s e t B  by    ( 5 , 5 )  }
                    With     BRect    .A   do
                        b e g i n
                       X  : = 1 5 ;
                       Y  : = 1 5 ;
                        end  ;
                    With     BRect    .B   do
                        b e g i n
                       X  : = 2 5 ;
                       Y  : = 2 5 ;
                        end  ;
                    {   P o i n t }
                    With     P  do
                        b e g i n
                       X  : = 1 5 ;
                       Y  : = 1 5 ;
                        end  ;
                    W r i t e l n ( 'A  |_|empty  |_|: |_|',ARect  . Empty    ) ;
                    W r i t e l n ( 'B  |_|empty  |_|: |_|',BRect  . Empty    ) ;
                    W r i t e l n ( 'A  |_|E q u a l|s_|B|_|: |_|',ARect .E q u a l s(BRect    ) ) ;
                    W r i t e l n ( 'A  |_|C o n t a i n|s_|( 1 5 , 1 5 ) |_|:,|_|'ARect.C o n t a i n(sP ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.4.2        TRect.Equals

Declaration:      Function  TRect.Equals  (R:  TRect):    Boolean;



                                                                                 287

                 _________________________________________________________________________________________________________________1*
 *5.4.___TRECT________
Description:      Equals  returns  True  if  the  rectangle  has  the  same  corner  points  A,B  as  the  rectangle  R,
                 and False otherwise.

       Errors:    None.

     See also:    Empty (287), Contains (288)


                 For an example, see TRect.Empty (287)
                 15.4.3        TRect.Contains

Declaration:      Function  TRect.Contains  (P:  TPoint):    Boolean;

Description:      Contains  returns  True  if  the  point  P  is  contained  in  the  rectangle  (including  borders),
                 False otherwise.

       Errors:    None.

     See also:    Intersect (289), Equals (287)
                 15.4.4        TRect.Copy

Declaration:      Procedure  TRect.Copy  (R:  TRect);

Description:      Assigns  the  rectangle  R  to  the  object.  After  the  call  to  Copy,  the  rectangle  R  has  been
                 copied to the object that invoked Copy.

       Errors:    None.

     See also:    Assign (291)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex2  ;


                 {  Program       to    d e m o n s t r a t eTRect   . Copy    }


                 Uses     o b j e c t s;


                 Var    ARect    ,BRect    , CRect     :   TRect   ;


                 b e g i n
                    ARect    . A s s i g n( 1 0 , 1 0 , 2 0 , 2 0 ) ;
                    BRect    . A s s i g n( 1 5 , 1 5 , 2 5 , 2 5 ) ;
                    CRect    . Copy   (ARect    ) ;
                    I f  ARect    . E q u a l s(CRect    )  Then
                        W r i t e l n( ' ARect    |_|e q u a l|s_|CRect  ')
                    E l s e
                        W r i t e l n( ' ARect    |_|d o e s|_|not|_|e q u a|l_|CRect  |_|! ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.4.5        TRect.Union

Declaration:      Procedure  TRect.Union  (R:  TRect);

Description:      Union enlarges the current rectangle so that it becomes the union of the current rectangle
                 with the rectangle R.
                                                                                 288

                 _________________________________________________________________________________________________________________1*
 *5.4.___TRECT________
       Errors:    None.

     See also:    Intersect (289)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex3  ;


                 {  Program       to    d e m o n s t r a t eTRect   . Union     }


                 Uses     o b j e c t s;



                 Var    ARect    ,BRect    , CRect     :   TRect   ;


                 b e g i n
                    ARect    . A s s i g n( 1 0 , 1 0 , 2 0 , 2 0 ) ;
                    BRect    . A s s i g n( 1 5 , 1 5 , 2 5 , 2 5 ) ;
                    {   CRect     i s  u n i o n  o f  ARect     and    BRect      }
                    CRect    . A s s i g n( 1 0 , 1 0 , 2 5 , 2 5 ) ;
                    {   C a l c u l a t ei t   e x p l i c i t l}y
                    ARect    . Union   ( BRect    ) ;
                    I f  ARect    . E q u a l s(CRect    )  Then
                        W r i t e l n( ' ARect    |_|e q u a l|s_|CRect  ')
                    E l s e
                        W r i t e l n( ' ARect    |_|d o e s|_|not|_|e q u a|l_|CRect  |_|! ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.4.6        TRect.Intersect

Declaration:      Procedure  TRect.Intersect  (R:  TRect);

Description:      Intersect  makes  the  intersection  of  the  current  rectangle  with  R.  If  the  intersection  is
                 empty, then the rectangle is set to the empty rectangle at coordinate (0,0).

       Errors:    None.

     See also:    Union (288)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex4  ;


                 {  Program       to    d e m o n s t r a t eTRect   . I n t e r s e c t}


                 Uses     o b j e c t s;



                 Var    ARect    ,BRect    , CRect     :   TRect   ;


                 b e g i n
                    ARect    . A s s i g n( 1 0 , 1 0 , 2 0 , 2 0 ) ;
                    BRect    . A s s i g n( 1 5 , 1 5 , 2 5 , 2 5 ) ;
                    {   CRect     i s   i n t e r s e c t i o no f ARect      and    BRect     }
                    CRect    . A s s i g n( 1 5 , 1 5 , 2 0 , 2 0 ) ;
                    {   C a l c u l a t ei t   e x p l i c i t l}y
                    ARect    . I n t e r s e c(tBRect    ) ;
                    I f  ARect    . E q u a l s(CRect    )  Then
                        W r i t e l n( ' ARect    |_|e q u a l|s_|CRect  ')
                    E l s e



                                                                                 289

                 _________________________________________________________________________________________________________________1*
 *5.4.___TRECT________
                        W r i t e l n( ' ARect    |_|d o e s|_|not|_|e q u a|l_|CRect  |_|! ') ;
                    BRect    . A s s i g n( 2 5 , 2 5 , 3 0 , 3 0 ) ;
                    A r e c t. I n t e r s e c(tBRect    ) ;
                    I f  ARect    . Empty     Then
                        W r i t e l n( ' ARect    |_|i s|_|empty  ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.4.7        TRect.Move

Declaration:      Procedure  TRect.Move  (ADX,  ADY:  Sw__ Integer);

Description:      Move moves the current rectangle along a vector with components (ADX,ADY). It adds ADX
                 to the X-coordinate of both corner points, and ADY to both end points.

       Errors:    None.

     See also:    Grow (290)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex5  ;


                 {  Program       to    d e m o n s t r a t eTRect   . Move    }


                 Uses     o b j e c t s;



                 Var    ARect    ,BRect      :  TRect    ;


                 b e g i n
                    ARect    . A s s i g n( 1 0 , 1 0 , 2 0 , 2 0 ) ;
                    ARect    .Move    ( 5 , 5 ) ;
                    / /   B r e c t s h o u l d be   where      new    ARect     i s .
                    BRect    . A s s i g n( 1 5 , 1 5 , 2 5 , 2 5 ) ;
                    I f  ARect    . E q u a l s(BRect    )  Then
                        W r i t e l n( ' ARect    |_|e q u a l|s_|BRect  ')
                    E l s e
                        W r i t e l n( ' ARect    |_|d o e s|_|not|_|e q u a|l_|BRect  |_|! ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.4.8        TRect.Grow

Declaration:      Procedure  TRect.Grow  (ADX,  ADY:  Sw__ Integer);

Description:      Grow expands the rectangle with an amount ADX in the X direction (both on the left and
                 right side of the rectangle, thus adding a length 2*ADX to the width of the rectangle), and
                 an  amount  ADY  in  the  Y  direction  (both  on  the  top  and  the  bottom  side  of  the  rectangle,
                 adding a length 2*ADY to the height of the rectangle.

                 ADX  and  ADY  can  be  negative.   If  the  resulting  rectangle  is  empty,  it  is  set  to  the  empty
                 rectangle at (0,0).

       Errors:    None.

     See also:    Move (290).
                                                                                 290

                 _____________________________________________________________________________________________________________15.5.*
 *___TOBJECT__________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex6  ;


                 {  Program       to    d e m o n s t r a t eTRect   . Grow    }


                 Uses     o b j e c t s;



                 Var    ARect    ,BRect      :  TRect    ;


                 b e g i n
                    ARect    . A s s i g n( 1 0 , 1 0 , 2 0 , 2 0 ) ;
                    ARect    . Grow   ( 5 , 5 ) ;
                    / /   B r e c t s h o u l d be   where      new    ARect     i s .
                    BRect    . A s s i g n( 5 , 5 , 2 5 , 2 5 ) ;
                    I f  ARect    . E q u a l s(BRect    )  Then
                        W r i t e l n( ' ARect    |_|e q u a l|s_|BRect  ')
                    E l s e
                        W r i t e l n( ' ARect    |_|d o e s|_|not|_|e q u a|l_|BRect  |_|! ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.4.9        TRect.Assign

Declaration:      Procedure  Trect.Assign  (XA,  YA,  XB,  YB:  Sw__ Integer);

Description:      Assign sets the corner points of the rectangle to (XA,YA) and (Xb,Yb).

       Errors:    None.

     See also:    Copy (288)


                 For an example, see TRect.Copy (288).
                 15.5          TOb ject


                 The full declaration of the TObject type is:


                 TYPE
                     TObject  =  OBJECT
                          CONSTRUCTOR  Init;
                          PROCEDURE  Free;
                          DESTRUCTOR  Done;Virtual;
                     END;
                     PObject  =  ^TObject;
                 15.5.1        TObject.Init

Declaration:      Constructor  TObject.Init;

Description:      Instantiates a new object of type TObject.  It fills the instance up with Zero bytes.

       Errors:    None.

     See also:    Free (292), Done (292)


                 For an example, see Free (292)



                                                                                 291

                 _____________________________________________________________________________________________________________15.5.*
 *___TOBJECT__________
                 15.5.2        TObject.Free

Declaration:      Procedure  TObject.Free;

Description:      Free calls the destructor of the object, and releases the memory occupied by the instance
                 of the object.

       Errors:    No  checking  is  performed  to  see  whether  self  is  nil  and  whether  the  object  is  indeed
                 allocated on the heap.

     See also:    Init (291), Done (292)

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       ex7  ;


                 {  Program       to    d e m o n s t r a t et h e TObject      .F r e e  c a l l }


                 Uses     O b j e c t s;


                 Var   O   :   P O b j e c t;


                 b e g i n
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                    / /   A l l o c a t ememory      f o r  o b j e c t.
                    O := New   (P O b j e c t, I n i t) ;
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                    / /  Free     memory      of    o b j e c t.
                    O ^ . f r e e;
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.5.3        TObject.Done

Declaration:      Destructor  TObject.Done;Virtual;

Description:      Done,  the  destructor  of  TObject  does  nothing.   It  is  mainly  intended  to  be  used  in  the
                 TObject.Free (292) method.

                 The destructore Done does not free the memory occupied by the object.

       Errors:    None.

     See also:    Free (292), Init (291)

                ___________________________________________________________________________________________________________________*
 *_____________
                 program       ex8  ;


                 {  Program       to    d e m o n s t r a t et h e TObject      .Done     c a l l }


                 Uses     O b j e c t s;


                 Var   O   :   P O b j e c t;


                 b e g i n
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                    / /   A l l o c a t ememory      f o r  o b j e c t.
                    O := New   (P O b j e c t, I n i t) ;
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                    O ^ .Done    ;
                    W r i t e l n ( ' Memavail      |_|: |_|',Memavail    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 292

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________
                 15.6          TStream


                 The  TStream  object  is  the  ancestor  for  all  streaming  objects,  i.e.   objects  that  have  the
                 capability to store and retrieve data.

                 It defines a number of methods that are common to all objects that implement streaming,
                 many of them are virtual, and are only implemented in the descendrnt types.

                 Programs should not instantiate objects of type TStream directly, but instead instantiate a
                 descendant type, such as TDosStream, TMemoryStream.

                 This is the full declaration of the TStream object:


                 TYPE
                     TStream  =  OBJECT  (TObject)
                               Status       :  Integer;  {  Stream  status  }
                               ErrorInfo  :  Integer;  {  Stream  error  info  }
                               StreamSize:  LongInt;  {  Stream  current  size  }
                               Position    :  LongInt;  {  Current  position  }
                          FUNCTION  Get:  PObject;
                          FUNCTION  StrRead:  PChar;
                          FUNCTION  GetPos:  Longint;  Virtual;
                          FUNCTION  GetSize:  Longint;  Virtual;
                          FUNCTION  ReadStr:  PString;
                          PROCEDURE  Open  (OpenMode:  Word);  Virtual;
                          PROCEDURE  Close;  Virtual;
                          PROCEDURE  Reset;
                          PROCEDURE  Flush;  Virtual;
                          PROCEDURE  Truncate;  Virtual;
                          PROCEDURE  Put  (P:  PObject);
                          PROCEDURE  StrWrite  (P:  PChar);
                          PROCEDURE  WriteStr  (P:  PString);
                          PROCEDURE  Seek  (Pos:  LongInt);  Virtual;
                          PROCEDURE  Error  (Code,  Info:  Integer);  Virtual;
                          PROCEDURE  Read  (Var  Buf;  Count:  Sw_Word);  Virtual;
                          PROCEDURE  Write  (Var  Buf;  Count:  Sw_Word);  Virtual;
                          PROCEDURE  CopyFrom  (Var  S:  TStream;  Count:  Longint);
                     END;
                     PStream  =  ^TStream;
                 15.6.1        TStream.Get

Declaration:      Function  TStream.Get  :    PObject;

Description:      Get reads an object definition from a stream, and returns a pointer to an instance of this
                 object.

       Errors:    On error, TStream.Status is set, and NIL is returned.

     See also:    Put (297)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex9  ;


                 {  Program       to    d e m o n s t r a t eTStream     .Get    and    TStream     . Put    }


                 Uses     O b j e c t s,MyObject      ;    {  D e f i n i t i o nand     r e g i s t r a t i o no f TMyObject      *
 * }



                                                                                 293

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________


                 Var    Obj    :  PMyObject       ;
                        S  :   PStream     ;


                 b e g i n
                    Obj  :=  New  ( PMyObject       , I n i t) ;
                    Obj   ^ .S e t F i e l d($1111    )  ;
                    W r i t e l n ( ' F i e l d|_|v a l u|e_|: |_|',Obj^ .G e t F i e l d) ;
                    {   S i n c e Stream       i s  an   a b s t r a c t t y p e,  we   i n s t a n t i a t ea   TMemoryStream     *
 *      }
                    S := New   (PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    S ^ .Put   (Obj   ) ;
                    W r i t e l n ( ' D i s p o s i n|g_|o b j e c't) ;
                    S ^ .Seek    ( 0 ) ;
                    D i s p o s e(Obj  , Done   ) ;
                    W r i t e l n ( ' R e a d i n g|_|o b j e c't) ;
                    Obj  :=  PMyObject       (S ^ . Get  ) ;
                    W r i t e l n ( ' F i e l d|_|V a l u|e_|: |_|',Obj^ .G e t F i e l d) ;
                    D i s p o s e(Obj  , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.6.2        TStream.StrRead

Declaration:      Function  TStream.StrRead:    PChar;

Description:      StrRead reads a string from the stream, allocates memory for it, and returns a pointer to
                 a null-terminated copy of the string on the heap.

       Errors:    On error, Nil is returned.

     See also:    StrWrite (298), ReadStr (296)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex10   ;


                 {
                 Program       to   d e m o n s t r a t et h e  TStream     . S t r R e a d TStream     . S t r W r i t e f u n c t*
 * i o n s
                 }


                 Uses     o b j e c t s;


                 Var   P   :   PChar   ;
                        S  :   PStream     ;


                 b e g i n
                    P :=  'C o n s t a n t|_|Pchar  |_|s t r i n'g;
                    W r i t e l n ( ' W r i t i n g|_|to|_|s t r e a|m_|: |_|",'P,' " ') ;
                    S := New   (PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    S ^ . S t r W r i t(eP ) ;
                    S ^ .Seek    ( 0 ) ;
                    P :=  N i l;
                    P := S ^ . S t r R e a d;
                    DisPose       ( S ,Done    ) ;
                    W r i t e l n ( ' Read   |_|from |_|s t r e a m|_|: |_|",'P,' " ') ;
                    Freemem     ( P , S t r l e n(P ) + 1 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 294

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________
                 15.6.3        TStream.GetPos

Declaration:      TSTream.GetPos  :    Longint;  Virtual;

Description:      If the stream's status is stOk, GetPos returns the current position in the stream.  Otherwise
                 it returns -1

       Errors:    -1 is returned if the status is an error condition.

     See also:    Seek (298), GetSize (295)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex11   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .GetPos       f u n c t i o n}


                 Uses     o b j e c t s;


                 Var    L  :   S t r i n g;
                        S  :   PStream     ;


                 b e g i n
                    L :=  'Some   |_|k i n d|_|o|f_|s t r i n'g;
                    S := New   (PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    W r i t e l n ( ' Stream    |_|p o s i t i o|n_|b e f o r|e_|w r i t:e|_|',S^ .GetPos    ) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    W r i t e l n ( ' Stream    |_|p o s i t i o|n_|a f t e|r_|w r i t|e_|: |_|',S^G.etPos   ) ;
                    D i s p o s e(S , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.6.4        TStream.GetSize

Declaration:      Function  TStream.GetSize:    Longint;  Virtual;

Description:      If  the  stream's  status  is  stOk  then  GetSize  returns  the  size  of  the  stream,  otherwise  it
                 returns -1.

       Errors:    -1 is returned if the status is an error condition.

     See also:    Seek (298), GetPos (295)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex12   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .G e t S i z e f u n c t i o n}


                 Uses     o b j e c t s;


                 Var    L  :   S t r i n g;
                        S  :   PStream     ;


                 b e g i n
                    L :=  'Some   |_|k i n d|_|o|f_|s t r i n'g;
                    S := New   (PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    W r i t e l n ( ' Stream    |_|s i z e|_|b e f o r|e_|w r i t:e|_|',S^ .G e t S i z e) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    W r i t e l n ( ' Stream    |_|s i z e|_|a f t e|r_|w r i t|e_|: |_|',S^G.e t S i z e) ;
                    D i s p o s e(S , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 295

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________
                 15.6.5        TStream.ReadStr

Declaration:      Function  TStream.ReadStr:    PString;

Description:      ReadStr reads a string from the stream, copies it to the heap and returns a pointer to this
                 copy.  The string is saved as a pascal string, and hence is NOT null terminated.

       Errors:    On error (e.g.  not enough memory), Nil is returned.

     See also:    StrRead (294)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex13   ;


                 {
                 Program       to   d e m o n s t r a t et h e  TStream     . R e a d S t r TStream     . W r i t e S t r f u n c t*
 * i o n s
                 }


                 Uses     o b j e c t s;


                 Var   P   :   P S t r i n g;
                        L  :   S t r i n g;
                        S  :   PStream     ;


                 b e g i n
                    L :=  'C o n s t a n t|_|s t r i n|g_|l i n'e;
                    W r i t e l n ( ' W r i t i n g|_|to|_|s t r e a|m_|: |_|",'L,' " ') ;
                    S := New   (PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    S ^ .Seek    ( 0 ) ;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t r(P) ;
                    DisPose       ( S ,Done    ) ;
                    W r i t e l n ( ' Read   |_|from |_|s t r e a m|_|: |_|",'L,' " ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.6.6        TStream.Open

Declaration:      Procedure  TStream.Open  (OpenMode:    Word);  Virtual;

Description:      Open is an abstract method, that should be overridden by descendent objects.  Since opening
                 a stream depends on the stream's type this is not surprising.

       Errors:    None.

     See also:    Close (296), Reset (297)


                 For an example, see TDosStream.Open (303).
                 15.6.7        TStream.Close

Declaration:      Procedure  TStream.Close;  Virtual;

Description:      Close  is  an  abstract  method,  that  should  be  overridden  by  descendent  objects.   Since
                 Closing a stream depends on the stream's type this is not surprising.

       Errors:    None.



                                                                                 296

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________
     See also:    Open (296), Reset (297)


                 for an example, see TDosStream.Open (303).
                 15.6.8        TStream.Reset

Declaration:      PROCEDURE  TStream.Reset;

Description:      Reset sets the stream's status to 0, as well as the ErrorInfo

       Errors:    None.

     See also:    Open (296), Close (296)
                 15.6.9        TStream.Flush

Declaration:      Procedure  TStream.Flush;  Virtual;

Description:      Flush is an abstract method that should be overridden by descendent objects.  It serves to
                 enable the programmer to tell streams that implement a buffer to clear the buffer.

       Errors:    None.

     See also:    Truncate (297)


                 for an example, see TBufStream.Flush (306).
                 15.6.10         TStream.Truncate

Declaration:      Procedure  TStream.Truncate;  Virtual;

Description:      Truncate  is  an  abstract  procedure  that  should  be  overridden  by  descendent  objects.   It
                 serves to enable the programmer to truncate the size of the stream to the current file position.

       Errors:    None.

     See also:    Seek (298)


                 For an example, see TDosStream.Truncate (302).
                 15.6.11         TStream.Put

Declaration:      Procedure  TStream.Put  (P:  PObject);

Description:      Put writes the object pointed to by P. P should be non-nil.  The object type must have been
                 registered with RegisterType (284).

                 After the object has been written, it can be read again with Get (293).

       Errors:    No check is done whether P is Nil or not.  Passing Nil will cause a run-time error 216 to
                 be generated.  If the object has not been registered, the status of the stream will be set to
                 stPutError.

     See also:    Get (293)


                 For an example, see TStream.Get (293);



                                                                                 297

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________
                 15.6.12         TStream.StrWrite

Declaration:      Procedure  TStream.StrWrite  (P:  PChar);

Description:      StrWrite writes the null-terminated string P to the stream.  P can only be 65355 bytes long.

       Errors:    None.

     See also:    WriteStr (298), StrRead (294), ReadStr (296)


                 For an example, see TStream.StrRead (294).
                 15.6.13         TStream.WriteStr

Declaration:      Procedure  TStream.WriteStr  (P:  PString);

Description:      StrWrite writes the pascal string pointed to by P to the stream.

       Errors:    None.

     See also:    StrWrite (298), StrRead (294), ReadStr (296)


                 For an example, see TStream.ReadStr (296).
                 15.6.14         TStream.Seek

Declaration:      PROCEDURE  TStream.Seek  (Pos:    LongInt);  Virtual;

Description:      Seek  sets  the  position  to  Pos.   This  position  is  counted  from  the  beginning,  and  is  zero
                 based.  (i.e.  seeek(0) sets the position pointer on the first byte of the stream)

       Errors:    If  Pos is larger than the stream size, Status is set to StSeekError.

     See also:    GetPos (295), GetSize (295)


                 For an example, see TDosStream.Seek (302).
                 15.6.15         TStream.Error

Declaration:      Procedure  TStream.Error  (Code,  Info:    Integer);  Virtual;

Description:      Error sets the stream's status to Code and ErrorInfo to Info.  If the StreamError proce-
                 dural variable is set, Error executes it, passing Self as an argument.

                 This  method  should  not  be  called  directly  from  a  program.   It  is  intended  to  be  used  in
                 descendent objects.

       Errors:    None.

     See also:
                                                                                 298

                 ____________________________________________________________________________________________________________15.6._*
 *__TSTREAM___________
                 15.6.16         TStream.Read

Declaration:      Procedure  TStream.Read  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      Read is an abstract method that should be overridden by descendent objects.

                 Read reads Count bytes from the stream into Buf.  It updates the position pointer, increasing
                 it's value with Count.  Buf must be large enough to contain Count bytes.

       Errors:    No checking is done to see if  Buf is large enough to contain Count bytes.

     See also:    Write (299), ReadStr (296), StrRead (294)


                ___________________________________________________________________________________________________________________*
 *_____________
                 program       ex18   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .Read     method      }


                 Uses     O b j e c t s;


                 Var    Buf1   ,Buf2     :   Array    [ 1 . . 1 0 0 0 ]of   Byte   ;
                        I  :   l o n g i n t;
                        S  :   PMemorySTream         ;


                 b e g i n
                    For    I :=1    to   1 0 0 0  do
                        Buf1   [ I] : =Random     ( 1 0 0 0 ) ;
                    Buf2   :=  Buf1   ;
                    S := New   (PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    S ^ .Write    ( Buf1   , S i z e O f(Buf1   ) ) ;
                    S ^ .Seek    ( 0 ) ;
                    For    I :=1    to   1 0 0 0  do
                        Buf1   [ I] : = 0 ;
                    S ^ .Read   ( Buf1   , S i z e O f(Buf1   ) ) ;
                    For    I :=1    to   1 0 0 0  do
                        I f  Buf1   [ I]<>   b u f 2[i ]   then
                           W r i t e l n ( ' B u f f e r|_|d i f f e r|s_|a|t_|p o s i t i|o_n|',I) ;
                    D i s p o s e(S , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.6.17         TStream.Write

Declaration:      Procedure  TStream.Write  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      Write is an abstract method that should be overridden by descendent objects.

                 Write writes Count bytes to the stream from Buf.  It updates the position pointer, increasing
                 it's value with Count.

       Errors:    No checking is done to see if  Buf actually contains Count bytes.

     See also:    Read (299), WriteStr (298), StrWrite (298)


                 For an example, see TStream.Read (299).
                 15.6.18         TStream.CopyFrom

Declaration:      Procedure  TStream.CopyFrom  (Var  S:  TStream;  Count:    Longint);
                                                                                 299

                 _____________________________________________________________________________________________________15.7.___TDOSS*
 *TREAM_______________
Description:      CopyFrom reads Count bytes from stream S and stores them in the current stream.  It uses
                 the Read (299) method to read the data, and the Write (299) method to write in the current
                 stream.

       Errors:    None.

     See also:    Read (299), Write (299)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex19   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .CopyFrom        f u n c t i o n}


                 Uses     o b j e c t s;


                 Var   P   :   P S t r i n g;
                        L  :   S t r i n g;
                        S1 , S2   :   PStream     ;


                 b e g i n
                    L :=  'C o n s t a n t|_|s t r i n|g_|l i n'e;
                    W r i t e l n ( ' W r i t i n g|_|to|_|s t r e a|m_|1 |_|: |_|",'L,' ")';
                    S1  := New  ( PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    S2  := New  ( PMemoryStream          , I n i t( 1 0 0 , 1 0 ) ) ;
                    S1  ^ .W r i t e S t r(@L  ) ;
                    S1  ^ .Seek   ( 0 ) ;
                    W r i t e l n ( ' C o p y i n g|_|c o n t e n t|s_|o|f_|s t r e|a_m|1t|_|o|_|s t r e|a_m|2)';
                    S2  ^ .Copyfrom      ( S1 ^ , S1 ^ . G e t S i z e) ;
                    S2  ^ .Seek   ( 0 ) ;
                    P := S2  ^ .R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t r(P) ;
                    D i s p o s e ( S1 , Done   ) ;
                    D i s p o s e ( S2 , Done   ) ;
                    W r i t e l n ( ' Read   |_|from |_|s t r e a m|_|2 |_|: |_|",'L,' ")';
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.7          TDosStream


                 TDosStream is a stream that stores it's contents in a file.  it overrides a couple of methods of
                 TSteam for this.

                 In addition to the fields inherited from TStream (see section 15.6, page 293), there are some
                 extra fields, that describe the file.  (mainly the name and the OS file handle)

                 No buffering in memory is done when using  TDosStream.  All data are written directly to
                 the file.  For a stream that buffers in memory, see section 15.8, page 304.

                 Here is the full declaration of the TDosStream object:


                 TYPE
                     TDosStream  =  OBJECT  (TStream)
                               Handle:  THandle;  {  DOS  file  handle  }
                               FName  :  AsciiZ;    {  AsciiZ  filename  }
                          CONSTRUCTOR  Init  (FileName:  FNameStr;  Mode:  Word);
                          DESTRUCTOR  Done;  Virtual;
                          PROCEDURE  Close;  Virtual;



                                                                                 300

                 _____________________________________________________________________________________________________15.7.___TDOSS*
 *TREAM_______________
                          PROCEDURE  Truncate;  Virtual;
                          PROCEDURE  Seek  (Pos:  LongInt);  Virtual;
                          PROCEDURE  Open  (OpenMode:  Word);  Virtual;
                          PROCEDURE  Read  (Var  Buf;  Count:  Sw_Word);  Virtual;
                          PROCEDURE  Write  (Var  Buf;  Count:  Sw_Word);  Virtual;
                     END;
                     PDosStream  =  ^TDosStream;
                 15.7.1        TDosStream.Init

Declaration:      Constructor  Init  (FileName:    FNameStr;  Mode:    Word);

Description:      Init instantiates an instance of  TDosStream.  The name of the file that contains (or will
                 contain)  the  data  of  the  stream  is  given  in  FileName.   The  Mode  parameter  determines
                 whether a new file should be created and what access rights you have on the file.  It can be
                 one of the following constants:

                 stCreate     Creates a new file.

                 stOpenRead         Read access only.

                 stOpenWrite         Write access only.

                 stOpen     Read and write access.

       Errors:    On error, Status is set to stInitError, and ErrorInfo is set to the dos error code.

     See also:    Done (301)


                 For an example, see TDosStream.Truncate (302).
                 15.7.2        TDosStream.Done

Declaration:      Destructor  TDosStream.Done;  Virtual;

Description:      Done closes the file if it was open and cleans up the instance of  TDosStream.

       Errors:    None.

     See also:    Init (301), Close (301)


                 for an example, see e.g.  TDosStream.Truncate (302).
                 15.7.3        TDosStream.Close

Declaration:      Pocedure  TDosStream.Close;  Virtual;

Description:      Close closes the file if it was open, and sets Handle to -1.  Contrary to Done (301) it does
                 not clean up the instance of  TDosStream

       Errors:    None.

     See also:    TStream.Close (296), Init (301), Done (301)


                 For an example, see TDosStream.Open (303).



                                                                                 301

                 _____________________________________________________________________________________________________15.7.___TDOSS*
 *TREAM_______________
                 15.7.4        TDosStream.Truncate

Declaration:      Procedure  TDosStream.Truncate;  Virtual;

Description:      If the status of the stream is stOK, then Truncate tries to truncate the stream size to the
                 current file position.

       Errors:    If  an  error  occurs,  the  stream's  status  is  set  to  stError  and  ErrorInfo  is  set  to  the  OS
                 error code.

     See also:    TStream.Truncate (297), GetSize (295)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex16   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .T r u n c a t e method      }


                 Uses     O b j e c t s;


                 Var    L  :   S t r i n g;
                       P   :   P S t r i n g;
                        S  :   PDosStream       ;   {  Only     one    w i t h  T r u n c a t ei m p l e m e n t e d.  }


                 b e g i n
                    L :=  'Some   |_|c o n s t a n|t_|s t r i n'g;
                    {   B u f f e r s i z e  o f  1 0 0  }
                    S := New   (PDosStream        , I n i t(' t e s t. d a t' , s t c r e a t e) ) ;
                    W r i t e l n ( ' W r i t i n g|_|",'L ,' " |_|to|_|s t r e a|m_|w i t|h_|h a n d l|e_|',S^ .H a n d l e) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    {   C l o s e c a l l s  f l u s h f i r s t }
                    S ^ . C l o s e;
                    S ^ .Open     ( stOpen     ) ;
                    W r i t e l n ( ' S i z e|_|o f|_|s t r e a|m_|i|s_|: |_|',S^G.e t S i z e) ;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t r(P) ;
                    W r i t e l n ( ' Read   |_|" ',L, ' " |_|from |_|s t r e a m|_|w i t|h_|h a n d l|e_|',S^ .H a n d l)e;
                    S ^ .Truncate      ;
                    W r i t e l n ( ' T r u n c a t e|d_|s t r e a.m|_|S i z|e_|i s|_|: |_|',S^G.e t S i z e) ;
                    S ^ . C l o s e;
                    D i s p o s e ( S ,Done    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.7.5        TDosStream.Seek

Declaration:      Procedure  TDosStream.Seek  (Pos:    LongInt);  Virtual;

Description:      If the stream's status is stOK, then Seek sets the file position to Pos.  Pos is a zero-based
                 offset, counted from the beginning of the file.

       Errors:    In case an error occurs, the stream's status is set to stSeekError, and the OS error code is
                 stored in ErrorInfo.

     See also:    TStream.Seek (298), GetPos (295)

                                                                                 302

                 _____________________________________________________________________________________________________15.7.___TDOSS*
 *TREAM_______________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex17   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .Seek     method      }


                 Uses     O b j e c t s;


                 Var    L  :   S t r i n g;
                        Marker      :  Word   ;
                       P   :   P S t r i n g;
                        S  :   PDosStream       ;


                 b e g i n
                    L :=  'Some   |_|c o n s t a n|t_|s t r i n'g;
                    {   B u f f e r s i z e  o f  1 0 0  }
                    S := New   (PDosStream        , I n i t(' t e s t. d a t' , s t c r e a t e) ) ;
                    W r i t e l n ( ' W r i t i n g|_|",'L ,' " |_|to|_|s t r e a.m' ) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    Marker     := S ^ .GetPos     ;
                    W r i t e l n ( ' S e t|_|m a r k e|r_|a t|_|',Marker   ) ;
                    L :=  'Some   |_|o t h e r|_|c o n s t a|n_t|S t r i n'g;
                    W r i t e l n ( ' W r i t i n g|_|",'L ,' " |_|to|_|s t r e a.m' ) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    S ^ . C l o s e;
                    S ^ .Open     ( stOpenRead        ) ;
                    W r i t e l n ( ' S i z e|_|o f|_|s t r e a|m_|i|s_|: |_|',S^G.e t S i z e) ;
                    W r i t e l n ( ' S e e k i n g|_|to|_|m a r k e'r) ;
                    S ^ .Seek   ( Marker     ) ;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t r(P) ;
                    W r i t e l n ( ' Read   |_|" ',L, ' " |_|from |_|s t r e a m. ') ;
                    S ^ . C l o s e;
                    D i s p o s e ( S ,Done    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.7.6        TDosStream.Open

Declaration:      Procedure  TDosStream.Open  (OpenMode:    Word);  Virtual;

Description:      If the stream's status is stOK, and the stream is closed then Open re-opens the file stream
                 with mode OpenMode.  This call can be used after a Close (301) call.

       Errors:    If an error occurs when re-opening the file, then Status is set to stOpenError, and the OS
                 error code is stored in ErrorInfo

     See also:    TStream.Open (296), Close (301)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex14   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .C l o s e  method     }


                 Uses     O b j e c t s;


                 Var    L  :   S t r i n g;
                       P   :   P S t r i n g;
                        S  :   PDosStream       ;   {  Only     one    w i t h  C l o s e i m p l e m e n t e.d }



                                                                                 303

                 _____________________________________________________________________________________________________15.8.___TBUFS*
 *TREAM_______________


                 b e g i n
                    L :=  'Some   |_|c o n s t a n|t_|s t r i n'g;
                    S := New   (PDosStream        , I n i t(' t e s t. d a t' , s t c r e a t e) ) ;
                    W r i t e l n ( ' W r i t i n g|_|",'L ,' " |_|to|_|s t r e a|m_|w i t|h_|h a n d l|e_|',S^ .H a n d l e) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    S ^ . C l o s e;
                    W r i t e l n ( ' C l o s e d|_|s t r e a.m|_|F i l|e_|h a n d l|e_|i|s_|',S^ .H a n d l e) ;
                    S ^ .Open     ( stOpenRead        ) ;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t r(P) ;
                    W r i t e l n ( ' Read   |_|" ',L, ' " |_|from |_|s t r e a m|_|w i t|h_|h a n d l|e_|',S^ .H a n d l)e;
                    S ^ . C l o s e;
                    D i s p o s e ( S ,Done    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.7.7        TDosStream.Read

Declaration:      Procedure  TDosStream.Read  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      If the Stream is open and the stream status is stOK then Read will read Count bytes from
                 the stream and place them in Buf.

       Errors:    In case of an error, Status is set to StReadError, and ErrorInfo gets the OS specific error,
                 or 0 when an attempt was made to read beyond the end of the stream.

     See also:    TStream.Read (299), Write (304)


                 For an example, see TStream.Read (299).
                 15.7.8        TDosStream.Write

Declaration:      Procedure  TDosStream.Write  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      If the Stream is open and the stream status is stOK then Write will write Count bytes from
                 Buf and place them in the stream.

       Errors:    In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                 error.

     See also:    TStream.Write (299), Read (304)


                 For an example, see TStream.Read (299).
                 15.8          TBufStream


                 Bufstream  implements  a  buffered  file  stream.   That  is,  all  data  written  to  the  stream  is
                 written  to  memory  first.   Only  when  the  buffer  is  full,  or  on  explicit  request,  the  data  is
                 written to disk.

                 Also, when reading from the stream, first the buffer is checked if there is any unread data in
                 it.  If so, this is read first.  If not the buffer is filled again, and then the data is read from the
                 buffer.

                 The size of the buffer is fixed and is set when constructing the file.

                 This is useful if you need heavy throughput for your stream, because it speeds up operations.



                                                                                 304

                 _____________________________________________________________________________________________________15.8.___TBUFS*
 *TREAM_______________
                 TYPE
                     TBufStream  =  OBJECT  (TDosStream)
                               LastMode:  Byte;            {  Last  buffer  mode  }
                               BufSize  :  Sw_Word;       {  Buffer  size  }
                               BufPtr    :  Sw_Word;       {  Buffer  start  }
                               BufEnd    :  Sw_Word;       {  Buffer  end  }
                               Buffer    :  PByteArray;  {  Buffer  allocated  }
                          CONSTRUCTOR  Init  (FileName:  FNameStr;  Mode,  Size:  Word);
                          DESTRUCTOR  Done;  Virtual;
                          PROCEDURE  Close;  Virtual;
                          PROCEDURE  Flush;  Virtual;
                          PROCEDURE  Truncate;  Virtual;
                          PROCEDURE  Seek  (Pos:  LongInt);  Virtual;
                          PROCEDURE  Open  (OpenMode:  Word);  Virtual;
                          PROCEDURE  Read  (Var  Buf;  Count:  Sw_Word);  Virtual;
                          PROCEDURE  Write  (Var  Buf;  Count:  Sw_Word);  Virtual;
                     END;
                     PBufStream  =  ^TBufStream;
                 15.8.1        TBufStream.Init

Declaration:      Constructor  Init  (FileName:    FNameStr;  Mode,Size:    Word);

Description:      Init instantiates an instance of  TBufStream.  The name of the file that contains (or will
                 contain)  the  data  of  the  stream  is  given  in  FileName.   The  Mode  parameter  determines
                 whether a new file should be created and what access rights you have on the file.  It can be
                 one of the following constants:

                 stCreate     Creates a new file.

                 stOpenRead         Read access only.

                 stOpenWrite         Write access only.

                 stOpen     Read and write access.

                 The  Size  parameter  determines  the  size  of  the  buffer  that  will  be  created.   It  should  be
                 different from zero.

       Errors:    On error, Status is set to stInitError, and ErrorInfo is set to the dos error code.

     See also:    TDosStream.Init (301), Done (305)


                 For an example see TBufStream.Flush (306).
                 15.8.2        TBufStream.Done

Declaration:      Destructor  TBufStream.Done;  Virtual;

Description:      Done flushes and closes the file if it was open and cleans up the instance of  TBufStream.

       Errors:    None.

     See also:    TDosStream.Done (301), Init (305), Close (306)


                 For an example see TBufStream.Flush (306).

                                                                                 305

                 _____________________________________________________________________________________________________15.8.___TBUFS*
 *TREAM_______________
                 15.8.3        TBufStream.Close

Declaration:      Pocedure  TBufStream.Close;  Virtual;

Description:      Close flushes and closes the file if it was open, and sets Handle to -1.  Contrary to Done
                 (305) it does not clean up the instance of  TBufStream

       Errors:    None.

     See also:    TStream.Close (296), Init (305), Done (305)


                 For an example see TBufStream.Flush (306).
                 15.8.4        TBufStream.Flush

Declaration:      Pocedure  TBufStream.Flush;  Virtual;

Description:      When the stream is in write mode, the contents of the buffer are written to disk, and the
                 buffer position is set to zero.

                 When the stream is in read mode, the buffer position is set to zero.

       Errors:    Write errors may occur if the file was in write mode.  see Write (308) for more info on the
                 errors.

     See also:    TStream.Close (296), Init (305), Done (305)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex15   ;


                 {  Program       to    d e m o n s t r a t et h e TStream      .F l u s h  method     }


                 Uses     O b j e c t s;


                 Var    L  :   S t r i n g;
                       P   :   P S t r i n g;
                        S  :   PBufStream       ;   {  Only     one    w i t h  F l u s h i m p l e m e n t e.d }


                 b e g i n
                    L :=  'Some   |_|c o n s t a n|t_|s t r i n'g;
                    {   B u f f e r s i z e  o f  1 0 0  }
                    S := New   (PBufStream        , I n i t(' t e s t. d a t' , s t c r e a t e, 1 0 0 ) ) ;
                    W r i t e l n ( ' W r i t i n g|_|",'L ,' " |_|to|_|s t r e a|m_|w i t|h_|h a n d l|e_|',S^ .H a n d l e) ;
                    S ^ . W r i t e S t(r@L  ) ;
                    {   At   t h i s  moment    ,   t h e r e i s  no    d a t a on    d i s k y e t .  }
                    S ^ . F l u s h;
                    {  Now     t h e r e i s .  }
                    S ^ . W r i t e S t(r@L  ) ;
                    {   C l o s e c a l l s  f l u s h f i r s t }
                    S ^ . C l o s e;
                    W r i t e l n ( ' C l o s e d|_|s t r e a.m|_|F i l|e_|h a n d l|e_|i|s_|',S^ .H a n d l e) ;
                    S ^ .Open     ( stOpenRead        ) ;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t r(P) ;
                    W r i t e l n ( ' Read   |_|" ',L, ' " |_|from |_|s t r e a m|_|w i t|h_|h a n d l|e_|',S^ .H a n d l)e;
                    S ^ . C l o s e;
                    D i s p o s e ( S ,Done    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 306

                 _____________________________________________________________________________________________________15.8.___TBUFS*
 *TREAM_______________
                 15.8.5        TBufStream.Truncate

Declaration:      Procedure  TBufStream.Truncate;  Virtual;

Description:      If  the  status  of  the  stream  is  stOK,  then  Truncate  tries  to  flush  the  buffer,  and  then
                 truncates the stream size to the current file position.

       Errors:    Errors can be those of  Flush (306) or TDosStream.Truncate (302).

     See also:    TStream.Truncate (297), TDosStream.Truncate (302), GetSize (295)


                 For an example, see TDosStream.Truncate (302).
                 15.8.6        TBufStream.Seek

Declaration:      Procedure  TBufStream.Seek  (Pos:    LongInt);  Virtual;

Description:      If the stream's status is stOK, then Seek sets the file position to Pos.  Pos is a zero-based
                 offset, counted from the beginning of the file.

       Errors:    In case an error occurs, the stream's status is set to stSeekError, and the OS error code is
                 stored in ErrorInfo.

     See also:    TStream.Seek (298), GetPos (295)


                 For an example, see TStream.Seek (298);
                 15.8.7        TBufStream.Open

Declaration:      Procedure  TBufStream.Open  (OpenMode:    Word);  Virtual;

Description:      If the stream's status is stOK, and the stream is closed then Open re-opens the file stream
                 with mode OpenMode.  This call can be used after a Close (306) call.

       Errors:    If an error occurs when re-opening the file, then Status is set to stOpenError, and the OS
                 error code is stored in ErrorInfo

     See also:    TStream.Open (296), Close (306)


                 For an example, see TDosStream.Open (303).
                 15.8.8        TBufStream.Read

Declaration:      Procedure  TBufStream.Read  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      If the Stream is open and the stream status is stOK then Read will read Count bytes from
                 the stream and place them in Buf.

                 Read will first try to read the data from the stream's internal buffer.  If insufficient data is
                 available, the buffer will be filled before contiunuing to read.  This process is repeated until
                 all needed data has been read.

       Errors:    In case of an error, Status is set to StReadError, and ErrorInfo gets the OS specific error,
                 or 0 when an attempt was made to read beyond the end of the stream.

     See also:    TStream.Read (299), Write (308)


                 For an example, see TStream.Read (299).



                                                                                 307

                 _____________________________________________________________________________________________15.9.___TMEMORYSTREAM*
 *____________________
                 15.8.9        TBufStream.Write

Declaration:      Procedure  TBufStream.Write  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      If the Stream is open and the stream status is stOK then Write will write Count bytes from
                 Buf and place them in the stream.

                 Write will first try to write the data to the stream's internal buffer.  When the internal buffer
                 is full, then the contents will be written to disk.  This process is repeated until all data has
                 been written.

       Errors:    In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                 error.

     See also:    TStream.Write (299), Read (307)


                 For an example, see TStream.Read (299).
                 15.9          TMemoryStream


                 The TMemoryStream object implements a stream that stores it's data in memory.  The data
                 is stored on the heap, with the possibility to specify the maximum amout of data, and the
                 the size of the memory blocks being used.


                 TYPE
                     TMemoryStream  =  OBJECT  (TStream)
                               BlkCount:  Sw_Word;            {  Number  of  segments  }
                               BlkSize  :  Word;                 {  Memory  block  size    }
                               MemSize  :  LongInt;            {  Memory  alloc  size    }
                               BlkList  :  PPointerArray;  {  Memory  block  list    }
                          CONSTRUCTOR  Init  (ALimit:  Longint;  ABlockSize:  Word);
                          DESTRUCTOR  Done;                                                                              Virtual;
                          PROCEDURE  Truncate;                                                                         Virtual;
                          PROCEDURE  Read  (Var  Buf;  Count:  Sw_Word);                                     Virtual;
                          PROCEDURE  Write  (Var  Buf;  Count:  Sw_Word);                                   Virtual;
                     END;
                     PMemoryStream  =  ^TMemoryStream;
                 15.9.1        TMemoryStream.Init

Declaration:      Constructor  TMemoryStream.Init  (ALimit:    Longint;  ABlockSize:    Word);

Description:      Init  instantiates  a  new  TMemoryStream  object.   The  memorystreamobject  will  initially
                 allocate at least ALimit bytes memory, divided into memory blocks of size ABlockSize.  The
                 number of blocks needed to get to ALimit bytes is rounded up.

                 By default, the number of blocks is 1, and the size of a block is 8192.  This is selected if you
                 specify 0 as the blocksize.

       Errors:    If the stream cannot allocate the initial memory needed for the memory blocks,  then the
                 stream's status is set to stInitError.

     See also:    Done (309)


                 For an example, see e.g TStream.CopyFrom (299).
                                                                                 308

                 _____________________________________________________________________________________________15.9.___TMEMORYSTREAM*
 *____________________
                 15.9.2        TMemoryStream.Done

Declaration:      Destructor  TMemoryStream.Done;  Virtual;

Description:      Done releases the memory blocks used by the stream, and then cleans up the memory used
                 by the stream object itself.

       Errors:    None.

     See also:    Init (308)


                 For an example, see e.g TStream.CopyFrom (299).
                 15.9.3        TMemoryStream.Truncate

Declaration:      Procedure  TMemoryStream.Truncate;  Virtual;

Description:      Truncate sets the size of the memory stream equal to the current position.  It de-allocates
                 any  memory-blocks  that  are  no  longer  needed,  so  that  the  new  size  of  the  stream  is  the
                 current position in the stream, rounded up to the first multiple of the stream blocksize.

       Errors:    If an error occurs during memory de-allocation, the stream's status is set to stError

     See also:    TStream.Truncate (297)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex20   ;


                 {  Program       to    d e m o n s t r a t et h e TMemoryStream          . T r u n c a t emethod      }


                 Uses     O b j e c t s;


                 Var    L  :   S t r i n g;
                       P   :   P S t r i n g;
                        S  :   PMemoryStream         ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    initMem     :=  Memavail      ;
                    L :=  'Some   |_|c o n s t a n|t_|s t r i n'g;
                    {   B u f f e r s i z e  o f  1 0 0  }
                    S := New   (PMemoryStream          , I n i t( 1 0 0 0 , 1 0 0 ) ) ;
                    W r i t e l n ( ' F r e e|_|memory   |_|: |_|',Memavail     ) ;
                    W r i t e l n ( ' W r i t i n g|_|1 0 0t|_|i m e|s_|",'L, ' " |_|to|_|s t r e a.m') ;
                    For    I :=1    to   1 0 0  do
                        S ^ .W r i t e S t r(@L ) ;
                    W r i t e l n ( ' F i n i s h e d. |_|F r e|e_|memory  |_|: |_|',Memavail    ) ;
                    S ^ .Seek    ( 1 0 0 ) ;
                    S ^ .Truncate      ;
                    W r i t e l n ( ' T r u n c a t e|d_|a t|_|b y t|e_|1 0 0 .F|_|r e|e_|memory |_|: |_|',Memavail     ) ;
                    D i s p o s e ( S ,Done    ) ;
                    W r i t e l n ( ' F i n i s h e d. |_|L o s|t_|',InitMem   - Memavail      , ' |_|B y t e.s' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.9.4        TMemoryStream.Read

Declaration:      Procedure  Read  (Var  Buf;  Count:    Sw__ Word);  Virtual;
                                                                                 309

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
Description:      Read reads Count bytes from the stream to Buf.  It updates the position of the stream.

       Errors:    If  there  is  not  enough  data  available,  no  data  is  read,  and  the  stream's  status  is  set  to
                 stReadError.

     See also:    TStream.Read, Write (310)


                 For an example, see TStream.Read (299).
                 15.9.5        TMemoryStream.Write

Declaration:      Procedure  Write  (Var  Buf;  Count:    Sw__ Word);  Virtual;

Description:      Write copies Count bytes from Buf to the stream.  It updates the position of the stream.

                 If not enough memory is available to hold the extra Count bytes, then the stream will try to
                 expand, by allocating as much blocks with size BlkSize (as specified in the constuctor call
                 Init (308)) as needed.

       Errors:    If the stream cannot allocate more memory, then the status is set to stWriteError

     See also:    TStream.Write (299), Read (309)


                 For an example, see TStream.Read (299).
                 15.10           TCollection


                 The TCollection object manages a collection of pointers or objects.  It also provides a series
                 of methods to manipulate these pointers or objects.

                 Whether or not objects are used depends on the kind of calls you use.  ALl kinds come in 2
                 flavors, one for objects, one for pointers.

                 This is the full declaration of the TCollection object:


                 TYPE
                     TItemList  =  Array  [0..MaxCollectionSize  -  1]  Of  Pointer;
                     PItemList  =  ^TItemList;


                     TCollection  =  OBJECT  (TObject)
                               Items:  PItemList;    {  Item  list  pointer  }
                               Count:  Sw_Integer;  {  Item  count  }
                               Limit:  Sw_Integer;  {  Item  limit  count  }
                               Delta:  Sw_Integer;  {  Inc  delta  size  }
                          Constructor  Init  (ALimit,  ADelta:  Sw_Integer);
                          Constructor  Load  (Var  S:  TStream);
                          Destructor  Done;  Virtual;
                          Function  At  (Index:  Sw_Integer):  Pointer;
                          Function  IndexOf  (Item:  Pointer):  Sw_Integer;  Virtual;
                          Function  GetItem  (Var  S:  TStream):  Pointer;  Virtual;
                          Function  LastThat  (Test:  Pointer):  Pointer;
                          Function  FirstThat  (Test:  Pointer):  Pointer;
                          Procedure  Pack;
                          Procedure  FreeAll;
                          Procedure  DeleteAll;



                                                                                 310

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                          Procedure  Free  (Item:  Pointer);
                          Procedure  Insert  (Item:  Pointer);  Virtual;
                          Procedure  Delete  (Item:  Pointer);
                          Procedure  AtFree  (Index:  Sw_Integer);
                          Procedure  FreeItem  (Item:  Pointer);  Virtual;
                          Procedure  AtDelete  (Index:  Sw_Integer);
                          Procedure  ForEach  (Action:  Pointer);
                          Procedure  SetLimit  (ALimit:  Sw_Integer);  Virtual;
                          Procedure  Error  (Code,  Info:  Integer);  Virtual;
                          Procedure  AtPut  (Index:  Sw_Integer;  Item:  Pointer);
                          Procedure  AtInsert  (Index:  Sw_Integer;  Item:  Pointer);
                          Procedure  Store  (Var  S:  TStream);
                          Procedure  PutItem  (Var  S:  TStream;  Item:  Pointer);  Virtual;
                     END;
                     PCollection  =  ^TCollection;
                 15.10.1         TCollection.Init

Declaration:      Constructor  TCollection.Init  (ALimit,  ADelta:    Sw__ Integer);

Description:      Init  initializes  a  new  instance  of  a  collection.   It  sets  the  (initial)  maximum  number  of
                 items  in  the  collection  to  ALimit.   ADelta  is  the  increase  size  :  The  number  of  memory
                 places that will be allocatiod in case ALimit is reached, and another element is added to the
                 collection.

       Errors:    None.

     See also:    Load (311), Done (312)


                 For an example, see TCollection.ForEach (321).
                 15.10.2         TCollection.Load

Declaration:      Constructor  TCollection.Load  (Var  S:  TStream);

Description:      Load initializes a new instance of a collection.  It reads from stream S the item count, the
                 item limit count,  and the increase size.  After that,  it reads the specified number of items
                 from the stream.

       Errors:    Errors returned can be those of  GetItem (314).

     See also:    Init (311), GetItem (314), Done (312).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex22   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.Load    method      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;
                        S  :   PMemoryStream         ;


                 b e g i n



                                                                                 311

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(100-   I ) ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' I n s e r t e d|_|',C^ .Count    , ' |_|o b j e c t's) ;
                    S := New   (PMemorySTream          , I n i t( 1 0 0 0 , 1 0 ) ) ;
                    C ^ . S t o r e(S ^ ) ;
                    C ^ . F r e e A l l;
                    D i s p o s e(C , Done   ) ;
                    S ^ .Seek    ( 0 ) ;
                    C ^ .Load   ( S ^ ) ;
                    W r i t e l n ( ' Read   |_|',C ^ .Count    , ' |_|o b j e c t|s_|from|_|s t r e a.m' ) ;
                    D i s p o s e(S , Done   ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.3         TCollection.Done

Declaration:      Destructor  TCollection.Done;  Virtual;

Description:      Done  frees  all  objects  in  the  collection,  and  then  releases  all  memory  occupied  by  the
                 instance.

       Errors:    None.

     See also:    Init (311), FreeAll (316)


                 For an example, see TCollection.ForEach (321).
                 15.10.4         TCollection.At

Declaration:      Function  TCollection.At  (Index:    Sw__ Integer):    Pointer;

Description:      At returns the item at position Index.

       Errors:    If  Index  is  less  than  zero  or  larger  than  the  number  of  items  in  the  collection,  seeplEr-
                 rorTCollection.Error  is  called  with  coIndexError  and  Index  as  arguments,  resulting  in  a
                 run-time error.

     See also:    Insert (318)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex23   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.At  method      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 b e g i n
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;



                                                                                 312

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(100-   I ) ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    For    I :=0    to   C ^ .Count    -1   do
                        b e g i n
                       M :=  C ^ .At  (I ) ;
                        W r i t e l n( ' O b j e c t|_|',i ,' |_|has |_|f i e l d|_|: |_|',M^ .G e t F i e l)d;
                        end  ;
                    C ^ . F r e e A l l;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.5         TCollection.IndexOf

Declaration:      Function  TCollection.IndexOf  (Item:    Pointer):    Sw__ Integer;  Virtual;

Description:      IndexOf returns the index of Item in the collection.  If Item isn't present in the collection,
                 -1 is returned.

       Errors:

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex24   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.I n d e x O fmethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M  ,Keep     :  PMyObject       ;
                        I  :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;
                    Keep   :=  N i l;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                        I f  Random    < 0 . 1  then
                         Keep   := M  ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    I f  Keep   = N i l  then
                        b e g i n
                        W r i t e l n( ' P l e a s e|_|run |_|a g a i.n|_|No|_|o b j e c|t_|s e l e c t e'd) ;
                        Halt   ( 1 ) ;
                        end  ;
                    W r i t e l n ( ' S e l e c t e d|_|o b j e c|t_|has|_|f i e l|d_|: |_|',Keep^ . G e t F i e l d) ;
                    Write     (  'S e l e c t e d|_|o b j e c|t_|has|_|i n d e|x_|: |_|',C^ .I n d e x O(fKeep   ) ) ;
                    W r i t e l n ( ' |_|s h o u l|d_|match |_|i t'' s |_|f i e l.d' ) ;
                    C ^ . F r e e A l l;



                                                                                 313

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.6         TCollection.GetItem

Declaration:      Function  TCollection.GetItem  (Var  S:  TStream):    Pointer;  Virtual;

Description:      GetItem  reads  a  single  item  off  the  stream  S,  and  returns  a  pointer  to  this  item.   This
                 method is used internally by the Load method, and should not be used directly.

       Errors:    Possible errors are the ones from TStream.Get (293).

     See also:    TStream.Get (293), seeplStoreTCollection.Store
                 15.10.7         TCollection.LastThat

Declaration:      Function  TCollection.LastThat  (Test:    Pointer):    Pointer;

Description:      This function returns the last item in the collection for which Test returns a non-nil result.
                 Test is a function that accepts 1 argument:  a pointer to an object, and that returns a pointer
                 as a result.

       Errors:    None.

     See also:    FirstThat (315)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex21   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.F o r e a c hmethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 F u n c t i o n C h e c k F i e l d(Dummy    :   P o i n t e r;P  :  PMyObject       )  :   L o n g i n t;


                 b e g i n
                    I f  P ^ . G e t F i e l d<56   then
                        C h e c k f i e l:d=1
                    e l s e
                        C h e c k F i e l:d= 0 ;
                 end  ;


                 b e g i n
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I ) ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' I n s e r t e d|_|',C^ .Count    , ' |_|o b j e c t's) ;
                    W r i t e l n ( ' L a s t|_|one |_|f o r|_|which |_|F i e l<d56 |_||_|has |_|i n d e|x_|(s h o u l|d_|be|_|5 4 *
 *) |_|:,|_|'
                                     C ^ . I n d e x O f(C ^ .L a s t T h a t(@ C h e c k F i e l)d) ) ;



                                                                                 314

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                    C ^ . F r e e A l l;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.8         TCollection.FirstThat

Declaration:      Function  TCollection.FirstThat  (Test:    Pointer):    Pointer;

Description:      This function returns the first item in the collection for which Test returns a non-nil result.
                 Test is a function that accepts 1 argument:  a pointer to an object, and that returns a pointer
                 as a result.

       Errors:    None.

     See also:    LastThat (314)

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex21   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.F i r s t T h a tmethod     }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 F u n c t i o n C h e c k F i e l d(Dummy    :   P o i n t e r;P  :  PMyObject       )  :   L o n g i n t;


                 b e g i n
                    I f  P ^ . G e t F i e l d>56   then
                        C h e c k f i e l:d=1
                    e l s e
                        C h e c k F i e l:d= 0 ;
                 end  ;


                 b e g i n
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I ) ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' I n s e r t e d|_|',C^ .Count    , ' |_|o b j e c t's) ;
                    W r i t e l n ( ' f i r s t|_|one|_|f o r|_|which  |_|F i e l>d56 |_||_|has|_|i n d e x|_|(s h o u l|d_|be|_|5 *
 *6 ) |_|:,|_|'
                                     C ^ . I n d e x O f(C ^ .F i r s t T h a t(@ C h e c k F i e l)d) ) ;
                    C ^ . F r e e A l l;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.9         TCollection.Pack

Declaration:      Procedure  TCollection.Pack;

Description:      Pack removes all Nil pointers from the collection, and adjusts Count to reflect this change.
                 No  memory  is  freed  as  a  result  of  this  call.   In  order  to  free  any  memory,  you  can  call
                 SetLimit with an argument of  Count after a call to Pack.



                                                                                 315

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
       Errors:    None.

     See also:    SetLimit (322)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex21   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.F i r s t T h a tmethod     }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 F u n c t i o n C h e c k F i e l d(Dummy    :   P o i n t e r;P  :  PMyObject       )  :   L o n g i n t;


                 b e g i n
                    I f  P ^ . G e t F i e l d>56   then
                        C h e c k f i e l:d=1
                    e l s e
                        C h e c k F i e l:d= 0 ;
                 end  ;


                 b e g i n
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I ) ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' I n s e r t e d|_|',C^ .Count    , ' |_|o b j e c t's) ;
                    W r i t e l n ( ' f i r s t|_|one|_|f o r|_|which  |_|F i e l>d56 |_||_|has|_|i n d e x|_|(s h o u l|d_|be|_|5 *
 *6 ) |_|:,|_|'
                                     C ^ . I n d e x O f(C ^ .F i r s t T h a t(@ C h e c k F i e l)d) ) ;
                    C ^ . F r e e A l l;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.10          TCollection.FreeAll

Declaration:      Procedure  TCollection.FreeAll;

Description:      FreeAll calls the destructor of each object in the collection.  It doesn't release any memory
                 occumpied by the collection itself, but it does set Count to zero.

       Errors:

     See also:    DeleteAll (317), FreeItem (320)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex28   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.F r e e A l lmethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n



                                                                                 316

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                       M   :   PMyObject      ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    InitMem     :=  Memavail      ;
                    W r i t e l n ( ' I n i t i a l|_|memory  |_|: |_|',InitMem    ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' Added    |_|1 0 0I|_|t e m.s|_|Memory   |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    Write     (  'L o s t |_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s') ;
                    Write         ( ' (S h o u l d|_|be|_|1 0 0 * ',SizeOF    (TMyObject       ) ) ;
                    W r i t e l n ( ' = ', 1 0 0 *S i z e O f(TMyObject       ) , ' ) ') ;
                    C ^ . F r e e A l l;
                    W r i t e l n ( ' F r e e d|_|a l|l_|o b j e c t.s|_|Memory  |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    W r i t e l n ( ' L o s t|_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s' ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.11          TCollection.DeleteAll

Declaration:      Procedure  TCollection.DeleteAll;

Description:      DeleteAll deletes all elements from the collection.  It just sets the Count variable to zero.
                 Contrary to FreeAll (316), DeletAll doesn't call the destructor of the objects.

       Errors:    None.

     See also:    FreeAll (316), Delete (319)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex29   ;


                 {
                  Program       to    d e m o n s t r a t et h e  T C o l l e c t i o.nD e l e t e A l lmethod
                  Compare        w i t h e x a m p l e 2 8 ,  where      F r e e A l l i s  u s e d.
                 }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    InitMem     :=  Memavail      ;
                    W r i t e l n ( ' I n i t i a l|_|memory  |_|: |_|',InitMem    ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);



                                                                                 317

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' Added    |_|1 0 0I|_|t e m.s|_|Memory   |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    Write     (  'L o s t |_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s') ;
                    Write         ( ' (S h o u l d|_|be|_|1 0 0 * ',SizeOF    (TMyObject       ) ) ;
                    W r i t e l n ( ' = ', 1 0 0 *S i z e O f(TMyObject       ) , ' ) ') ;
                    C ^ . D e l e t e A l;l
                    W r i t e l n ( ' D e l e t e d|_|a l|l_|o b j e c t.s|_|Memory  |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    W r i t e l n ( ' L o s t|_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s' ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.12          TCollection.Free

Declaration:      Procedure  TCollection.Free  (Item:    Pointer);

Description:      Free Deletes Item from the collection, and calls the destructor Done of the object.

       Errors:    If the Item is not in the collection, Error will be called with coIndexError.

     See also:    FreeItem (320),

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex30   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.F r e e method      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    InitMem     :=  Memavail      ;
                    W r i t e l n ( ' I n i t i a l|_|memory  |_|: |_|',InitMem    ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' Added    |_|1 0 0I|_|t e m.s|_|Memory   |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    Write     (  'L o s t |_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s') ;
                    Write         ( ' (S h o u l d|_|be|_|1 0 0 * ',SizeOF    (TMyObject       ) ) ;
                    W r i t e l n ( ' = ', 1 0 0 *S i z e O f(TMyObject       ) , ' ) ') ;
                    With     C ^  do
                        While     Count    >0   do   Free   ( At  (Count    - 1 ) ) ;
                    W r i t e l n ( ' F r e e d|_|a l|l_|o b j e c t.s|_|Memory  |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    W r i t e l n ( ' L o s t|_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s' ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.13          TCollection.Insert

Declaration:      Procedure  TCollection.Insert  (Item:    Pointer);  Virtual;



                                                                                 318

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
Description:      Insert inserts Item in the collection.  TCollection inserts this item at the end,  but de-
                 scendent objects may insert it at another place.

       Errors:    None.

     See also:    AtInsert (323), AtPut (322),
                 15.10.14          TCollection.Delete

Declaration:      Procedure  TCollection.Delete  (Item:    Pointer);

Description:      Delete deletes Item from the collection.  It doesn't call the item's destructor, though.  For
                 this the Free (318) call is provided.

       Errors:    If the Item is not in the collection, Error will be called with coIndexError.

     See also:    AtDelete (320),Free (318)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex31   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.D e l e t emethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    InitMem     :=  Memavail      ;
                    W r i t e l n ( ' I n i t i a l|_|memory  |_|: |_|',InitMem    ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' Added    |_|1 0 0I|_|t e m.s|_|Memory   |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    Write     (  'L o s t |_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s') ;
                    Write         ( ' (S h o u l d|_|be|_|1 0 0 * ',SizeOF    (TMyObject       ) ) ;
                    W r i t e l n ( ' = ', 1 0 0 *S i z e O f(TMyObject       ) , ' ) ') ;
                    With     C ^  do
                        While     Count    >0   do   D e l e t e(At  ( Count    - 1 ) ) ;
                    W r i t e l n ( ' F r e e d|_|a l|l_|o b j e c t.s|_|Memory  |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    W r i t e l n ( ' L o s t|_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s' ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.15          TCollection.AtFree

Declaration:      Procedure  TCollection.AtFree  (Index:    Sw__ Integer);

Description:      AtFree deletes the item at position Index in the collection, and calls the item's destructor
                 if it is not Nil.



                                                                                 319

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
       Errors:    If  Index isn't valid then Error (322) is called with CoIndexError.

     See also:    Free (318), AtDelete (320)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex32   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.A t F r e emethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    InitMem     :=  Memavail      ;
                    W r i t e l n ( ' I n i t i a l|_|memory  |_|: |_|',InitMem    ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' Added    |_|1 0 0I|_|t e m.s|_|Memory   |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    Write     (  'L o s t |_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s') ;
                    Write         ( ' (S h o u l d|_|be|_|1 0 0 * ',SizeOF    (TMyObject       ) ) ;
                    W r i t e l n ( ' = ', 1 0 0 *S i z e O f(TMyObject       ) , ' ) ') ;
                    With     C ^  do
                        While     Count    >0   do   A t F r e e( Count   -1);
                    W r i t e l n ( ' F r e e d|_|a l|l_|o b j e c t.s|_|Memory  |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    W r i t e l n ( ' L o s t|_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s' ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.16          TCollection.FreeItem

Declaration:      Procedure  TCollection.FreeItem  (Item:    Pointer);  Virtual;

Description:      FreeItem calls the destructor of  Item if it is not nil.

                 This function is used internally by the TCollection object, and should not be called directly.

       Errors:    None.

     See also:    Free (319), seeplAtFreeTCollection.AtFree
                 15.10.17          TCollection.AtDelete

Declaration:      Procedure  TCollection.AtDelete  (Index:    Sw__ Integer);

Description:      AtDelete deletes the pointer at position Index in the collection.  It doesn't call the object's
                 destructor.

       Errors:    If  Index isn't valid then Error (322) is called with CoIndexError.

     See also:    Delete (319)



                                                                                 320

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex33   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.A t D e l e t emethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I ,InitMem       :   L o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    InitMem     :=  Memavail      ;
                    W r i t e l n ( ' I n i t i a l|_|memory  |_|: |_|',InitMem    ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' Added    |_|1 0 0I|_|t e m.s|_|Memory   |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    Write     (  'L o s t |_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s') ;
                    Write         ( ' (S h o u l d|_|be|_|1 0 0 * ',SizeOF    (TMyObject       ) ) ;
                    W r i t e l n ( ' = ', 1 0 0 *S i z e O f(TMyObject       ) , ' ) ') ;
                    With     C ^  do
                        While     Count    >0   do   A t D e l e t e(Count    -1);
                    W r i t e l n ( ' F r e e d|_|a l|l_|o b j e c t.s|_|Memory  |_|a v a i l a b l|e_|: |_|',Memavail   ) ;
                    W r i t e l n ( ' L o s t|_|: |_|',Initmem   - Memavail      , ' |_|b y t e.s' ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.18          TCollection.ForEach

Declaration:      Procedure  TCollection.ForEach  (Action:    Pointer);

Description:      ForEach  calls  Action  for  each  element  in  the  collection,  and  passes  the  element  as  an
                 argument to Action.

                 Action is a procedural type variable that accepts a pointer as an argument.

       Errors:    None.

     See also:    FirstThat (315), LastThat (314)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex21   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.F o r e a c hmethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 Procedure        P r i n t F i e l d( Dummy    :  P o i n t e r;P   :  PMyObject       ) ;
                                                                                 321

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________


                 b e g i n
                    W r i t e l n ( ' F i e l d|_|: |_|',P^ .G e t F i e l)d;
                 end  ;


                 b e g i n
                    C := New   ( P C o l l e c t i o,nI n i t( 1 0 0 , 1 0 ) ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(100-   I ) ;
                       C  ^ .I n s e r t(M ) ;
                        end  ;
                    W r i t e l n ( ' I n s e r t e d|_|',C^ .Count    , ' |_|o b j e c t's) ;
                    C ^ .ForEach      ( @ P r i n t F i e l)d;
                    C ^ . F r e e A l l;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.19          TCollection.SetLimit

Declaration:      Procedure  TCollection.SetLimit  (ALimit:    Sw__ Integer);  Virtual;

Description:      SetLimit sets the maximum number of elements in the collection.  ALimit must not be less
                 than Count, and should not be larger than MaxCollectionSize

       Errors:    None.

     See also:    Init (311)


                 For an example, see Pack (315).
                 15.10.20          TCollection.Error

Declaration:      Procedure  TCollection.Error  (Code,  Info:    Integer);  Virtual;

Description:      Error  is  called  by  the  various  TCollection  methods  in  case  of  an  error  condition.  The
                 default behaviour is to make a call to RunError with an error of  212-Code.

                 This method can be overridden by descendent objects to implement a different error-handling.

       Errors:

     See also:    Abstract (284)
                 15.10.21          TCollection.AtPut

Declaration:      Procedure  TCollection.AtPut  (Index:    Sw__ Integer;  Item:    Pointer);

Description:      AtPut sets the element at position Index in the collection to Item.  Any previous value is
                 overwritten.

       Errors:    If  Index isn't valid then Error (322) is called with CoIndexError.

     See also:


                 For an example, see Pack (315).



                                                                                 322

                 ___________________________________________________________________________________________________15.10.___TCOLLE*
 *CTION_______________
                 15.10.22          TCollection.AtInsert

Declaration:      Procedure  TCollection.AtInsert  (Index:    Sw__ Integer;  Item:    Pointer);

Description:      AtInsert  inserts  Item  in  the  collection  at  position  Index,  shifting  all  elements  by  one
                 position.  In case the current limit is reached, the collection will try to expand with a call to
                 SetLimit

       Errors:    If  Index isn't valid then Error (322) is called with CoIndexError.  If the collection fails to
                 expand, then coOverFlow is passd to Error.

     See also:    Insert (318)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex34   ;


                 {  Program       to    d e m o n s t r a t et h e T C o l l e c t i o n.A t I n s e r tmethod      }


                 Uses     O b j e c t s,MyObject      ;  {  For    TMyObject         d e f i n i t i o nand    r e g i s t r a t i *
 *o n}


                 Var   C   :   P C o l l e c t i o;n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 Procedure        P r i n t F i e l d( Dummy    :  P o i n t e r;P   :  PMyObject       ) ;


                 b e g i n
                    W r i t e l n ( ' F i e l d|_|: |_|',P^ .G e t F i e l)d;
                 end  ;



                 b e g i n
                    Randomize       ;
                    C := New   ( P C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    W r i t e l n ( ' I n s e r t i n g|_|1 0 0r|_|e c o r|d_s|a|t_|random  |_|p l a c e.s' ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(I-1);
                        I f  I =1   then
                           C ^ . I n s e r t(M)
                        e l s e
                           With     C ^  do
                               A t I n s e r t(Random    ( Count   ) ,M  ) ;
                        end  ;
                    W r i t e l n ( ' V a l u e s|_|: |_|') ;
                    C ^ . F o r e a c h(@ P r i n t F i e l)d;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.10.23          TCollection.Store

Declaration:      Procedure  TCollection.Store  (Var  S:  TStream);

Description:      Store  writes  the  collection  to  the  stream  S.  It  does  this  by  writeing  the  current  Count,
                 Limit and Delta to the stream, and then writing each item to the stream.

                 The contents of the stream are then suitable for instantiating another collection with Load
                 (311).



                                                                                 323

                 ______________________________________________________________________________________15.11.___TSORTEDCOLLECTION__*
 *____________________
       Errors:    Errors returned are those by TStream.Put (297).

     See also:    Load (311), PutItem (324)


                 For an example, see seeplLoadTCollection.Load.
                 15.10.24          TCollection.PutItem

Declaration:      Procedure  TCollection.PutItem  (Var  S:  TStream;  Item:    Pointer);  Virtual;

Description:      PutItem writes Item to stream S. This method is used internaly by the TCollection object,
                 and should not be called directly.

       Errors:    Errors are those returned by TStream.Put (297).

     See also:    Store (323), GetItem (314).
                 15.11           TSortedCollection


                 TSortedCollection is an abstract class, implementing a sorted collection.  You should never
                 use  an  instance  of  TSortedCollection  directly,  instead  you  should  declare  a  descendent
                 type, and override the Compare (326) method.

                 Because the collection is ordered, TSortedCollection overrides some TCollection methods,
                 to provide faster routines for lookup.

                 The Compare (326) method decides how elements in the collection should be ordered.  Since
                 TCollection has no way of knowing how to order pointers, you must override the compare
                 method.

                 Additionally, TCollection provides a means to filter out duplicates.  if you set Duplicates
                 to False (the default) then duplicates will not be allowed.

                 Here is the complete declaration of  TSortedCollection


                 TYPE
                     TSortedCollection  =  OBJECT  (TCollection)
                               Duplicates:  Boolean;  {  Duplicates  flag  }
                          Constructor  Init  (ALimit,  ADelta:  Sw_Integer);
                          Constructor  Load  (Var  S:  TStream);
                          Function  KeyOf  (Item:  Pointer):  Pointer;  Virtual;
                          Function  IndexOf  (Item:  Pointer):  Sw_Integer;  Virtual;
                          Function  Compare  (Key1,  Key2:  Pointer):  Sw_Integer;  Virtual;
                          Function  Search  (Key:  Pointer;  Var  Index:  Sw_Integer):  Boolean;Virtual;
                          Procedure  Insert  (Item:  Pointer);  Virtual;
                          Procedure  Store  (Var  S:  TStream);
                     END;
                     PSortedCollection  =  ^TSortedCollection;


                 In the subsequent examples, the following descendent of  TSortedCollection is used:

                ___________________________________________________________________________________________________________________*
 *_____________
                 Unit    MySortC      ;


                 I n t e r f a c e


                 Uses     O b j e c t s;



                                                                                 324

                 ______________________________________________________________________________________15.11.___TSORTEDCOLLECTION__*
 *____________________


                 Type
                    P M y S o r t e d C o l l e c t i o=n ^ T M y S o r t e d C o l l e c t i o;n
                    T M y S o r t e d C o l l e c t i o=n  Object    ( T S o r t e d C o l l e c t i)o n
                             F u n c t i o n Compare      ( Key1   , Key2     :  P o i n t e r) :  S w __i n t e g e;r  v i r t u a*
 * l;
                             end  ;


                 I m p l e m e n t a t i o n


                 Uses    MyObject      ;


                 F u n c t i o n T M y S o r t e d C o l l e c t i.oCnompare     ( Key1   , Key2    :   P o i n t e r)  :s w __i n *
 *t e g e r;


                 b e g i n
                    Compare     :=  PMyobject       (Key1   ) ^ . G e t F i e l d-   PMyObject      ( Key2   ) ^ . G e t F i e l;d
                 end  ;


                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.11.1         TSortedCollection.Init

Declaration:      Constructor  TSortedCollection.Init  (ALimit,  ADelta:    Sw__ Integer);

Description:      Init calls the inherited constuctor (see TCollection.Init (311)) and sets the Duplicates flag
                 to false.

                 You  should  not  call  this  method  directly,  since  TSortedCollection  is  a  abstract  class.
                 Instead, the descendent classes should call it via the inherited keyword.

       Errors:    None.

     See also:    Load (325), Done (312)


                 For an example, see
                 15.11.2         TSortedCollection.Load

Declaration:      Constructor  Load  (Var  S:  TStream);

Description:      Load calls the inherited constuctor (see TCollection.Load (311)) and reads the Duplicates
                 flag from the stream..

                 You  should  not  call  this  method  directly,  since  TSortedCollection  is  a  abstract  class.
                 Instead, the descendent classes should call it via the inherited keyword.

       Errors:    None.

     See also:    Init (325), Done (312)


                 For an example, see TCollection.Load (311).
                 15.11.3         TSortedCollection.KeyOf

Declaration:      Function  TSortedCollection.KeyOf  (Item:    Pointer):    Pointer;  Virtual;
                                                                                 325

                 ______________________________________________________________________________________15.11.___TSORTEDCOLLECTION__*
 *____________________
Description:      KeyOf returns the key associated with Item.  TSortedCollection returns the item itself as
                 the key, descendent objects can override this method to calculate a (unique) key based on
                 the item passed (such as hash values).

                 Keys are used to sort the objects, they are used to search and sort the items in the collection.
                 If descendent types override this method then it allows possibly for faster search/sort methods
                 based on keys rather than on the objects themselves.

       Errors:    None.

     See also:    IndexOf  (326), Compare (326).
                 15.11.4         TSortedCollection.IndexOf

Declaration:      Function  TSortedCollection.IndexOf  (Item:    Pointer):    Sw__ Integer;  Virtual;

Description:      IndexOf returns the index of Item in the collection.  It searches for the object based on it's
                 key.  If duplicates are allowed, then it returns the index of last object that matches Item.

                 In case Item is not found in the collection, -1 is returned.

       Errors:    None.

     See also:    Search (327), Compare (326).


                 For an example, see TCollection.IndexOf  (313)
                 15.11.5         TSortedCollection.Compare

Declaration:      Function  TSortedCollection.Compare  (Key1,  Key2:    Pointer):    Sw__ Integer;  Virtual;

Description:      Compare is an abstract method that should be overridden by descendent objects in order
                 to compare two items in the collection.  This method is used in the Search (327) method and
                 in the Insert (328) method to determine the ordering of the objects.

                 The function should compare the two keys of items and return the following function results:

                 Result < 0     If  Key1 is logically before Key2 (Key1<Key2)

                 Result = 0       If  Key1 and Key2 are equal.  (Key1=Key2)

                 Result > 0      If  Key1 is logically after Key2 (Key1>Key2)

       Errors:    An  'abstract  run-time  error'  will  be  generated  if  you  call  TSortedCollection.Compare
                 directly.

     See also:    IndexOf  (326), Search (327)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Unit    MySortC      ;


                 I n t e r f a c e


                 Uses     O b j e c t s;


                 Type
                    P M y S o r t e d C o l l e c t i o=n ^ T M y S o r t e d C o l l e c t i o;n
                    T M y S o r t e d C o l l e c t i o=n  Object    ( T S o r t e d C o l l e c t i)o n
                             F u n c t i o n Compare      ( Key1   , Key2     :  P o i n t e r) :  S w __i n t e g e;r  v i r t u a*
 * l;
                             end  ;



                                                                                 326

                 ______________________________________________________________________________________15.11.___TSORTEDCOLLECTION__*
 *____________________


                 I m p l e m e n t a t i o n


                 Uses    MyObject      ;


                 F u n c t i o n T M y S o r t e d C o l l e c t i.oCnompare     ( Key1   , Key2    :   P o i n t e r)  :s w __i n *
 *t e g e r;


                 b e g i n
                    Compare     :=  PMyobject       (Key1   ) ^ . G e t F i e l d-   PMyObject      ( Key2   ) ^ . G e t F i e l;d
                 end  ;


                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.11.6         TSortedCollection.Search

Declaration:      Function  TSortedCollection.Search  (Key:    Pointer;  Var  Index:    Sw__ Integer):    Boolean;Virtual;

Description:      Search looks for the item with key Key and returns the position of the item (if present) in
                 the collection in Index.

                 Instead of a linear search as TCollection does,  TSortedCollection uses a binary search
                 based  on  the  keys  of  the  objects.   It  uses  the  Compare  (326)  function  to  implement  this
                 search.

                 If the item is found, Search returns True, otherwise False is returned.

       Errors:    None.

     See also:    IndexOf  (313).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex36   ;


                 {  Program       to    d e m o n s t r a t et h e T S o r t e d C o l l e c t i o.nI n s e r tmethod      }


                 Uses     O b j e c t s,MyObject     , MySortC     ;
                   {  For    TMyObject       , T M y S o r t e d C o l l e c t i odne f i n i t i o nand    r e g i s t r a t i o n}


                 Var   C   :   P S o r t e d C o l l e c t i;o n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 Procedure        P r i n t F i e l d( Dummy    :  P o i n t e r;P   :  PMyObject       ) ;


                 b e g i n
                    W r i t e l n ( ' F i e l d|_|: |_|',P^ .G e t F i e l)d;
                 end  ;



                 b e g i n
                    Randomize       ;
                    C := New   ( P M y S o r t e d C o l l e c t i,oInn i t( 1 2 0 , 1 0 ) ) ;
                    C ^ . D u p l i c a t e:s=True   ;
                    W r i t e l n ( ' I n s e r t i n g|_|1 0 0r|_|e c o r|d_s|a|t_|random  |_|p l a c e.s' ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(Random    ( 1 0 0 ) ) ;
                       C  ^ .I n s e r t(M )



                                                                                 327

                 ______________________________________________________________________________________15.11.___TSORTEDCOLLECTION__*
 *____________________
                        end  ;
                    M := New   (PMyObject       , I n i t) ;
                    Repeat     ;
                        Write     ( ' V a l u e|_|to|_|s e a r c|h_|f o|r_|(-1 |_|s t o p)s|_|:)';
                        read    ( I ) ;
                        I f  I<>-1     then
                           b e g i n
                           M ^ . S e t F i e l(di ) ;
                           I f  Not    C ^ . S e a r c h (M , I )  then
                               W r i t e l n( ' No  |_|s u c|h_|v a l u|e_|f o u n'd)
                           e l s e
                               b e g i n
                               Write     ( ' V a l u e|_|',PMyObject      ( C ^ .At  ( I) ) ^ .G e t F i e l d) ;
                               W r i t e l n(  ' |_|p r e s e n|t_|a|t_|p o s i t i|o_n|',I) ;
                               end  ;
                           end   ;
                    U n t i l  I=-1;
                    D i s p o s e(M , Done   ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.11.7         TSortedCollection.Insert

Declaration:      Procedure  TSortedCollection.Insert  (Item:    Pointer);  Virtual;

Description:      Insert inserts an item in the collection at the correct position, such that the collection is
                 ordered at all times.  You should never use Atinsert (323), since then the collection ordering
                 is not guaranteed.

                 If  Item is already present in the collection, and Duplicates is False, the item will not be
                 inserted.

       Errors:    None.

     See also:    AtInsert (323)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex35   ;


                 {  Program       to    d e m o n s t r a t et h e T S o r t e d C o l l e c t i o.nI n s e r tmethod      }


                 Uses     O b j e c t s,MyObject     , MySortC     ;
                   {  For    TMyObject       , T M y S o r t e d C o l l e c t i odne f i n i t i o nand    r e g i s t r a t i o n}


                 Var   C   :   P S o r t e d C o l l e c t i;o n
                       M   :   PMyObject      ;
                        I  :   L o n g i n t;


                 Procedure        P r i n t F i e l d( Dummy    :  P o i n t e r;P   :  PMyObject       ) ;


                 b e g i n
                    W r i t e l n ( ' F i e l d|_|: |_|',P^ .G e t F i e l)d;
                 end  ;



                 b e g i n
                    Randomize       ;
                    C := New   ( P M y S o r t e d C o l l e c t i,oInn i t( 1 2 0 , 1 0 ) ) ;



                                                                                 328

                 _______________________________________________________________________________________15.12.___TSTRINGCOLLECTION_*
 *____________________
                    W r i t e l n ( ' I n s e r t i n g|_|1 0 0r|_|e c o r|d_s|a|t_|random  |_|p l a c e.s' ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                       M :=  New  ( PMyObject       , I n i t) ;
                       M  ^ .S e t F i e l d(Random    ( 1 0 0 ) ) ;
                       C  ^ .I n s e r t(M )
                        end  ;
                    W r i t e l n ( ' V a l u e s|_|: |_|') ;
                    C ^ . F o r e a c h(@ P r i n t F i e l)d;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.11.8         TSortedCollection.Store

Declaration:      Procedure  TSortedCollection.Store  (Var  S:  TStream);

Description:      Store writes the collection to the stream S. It does this by calling the inherited TCollec-
                 tion.Store (323), and then writing the Duplicates flag to the stream.

                 After a Store, the collection can be loaded from the stream with the constructor Load (325)

       Errors:    Errors can be those of  TStream.Put (297).

     See also:    Load (325)


                 For an example, see TCollection.Load (311).
                 15.12           TStringCollection


                 The TStringCollection object manages a sorted collection of pascal strings.  To this end,
                 it overrides the Compare (326) method of  TSortedCollection,  and it introduces methods
                 to read/write strings from a stream.

                 Here is the full declaration of the TStringCollection object:


                 TYPE
                     TStringCollection  =  OBJECT  (TSortedCollection)
                          Function  GetItem  (Var  S:  TStream):  Pointer;  Virtual;
                          Function  Compare  (Key1,  Key2:  Pointer):  Sw_Integer;  Virtual;
                          Procedure  FreeItem  (Item:  Pointer);  Virtual;
                          Procedure  PutItem  (Var  S:  TStream;  Item:  Pointer);  Virtual;
                     END;
                     PStringCollection  =  ^TStringCollection;
                 15.12.1         TStringCollection.GetItem

Declaration:      Function  TStringCollection.GetItem  (Var  S:  TStream):    Pointer;  Virtual;

Description:      GetItem reads a string from the stream S and returns a pointer to it.  It doesn't insert the
                 string in the collection.

                 This method is primarily introduced to be able to load and store the collection from and to
                 a stream.

       Errors:    The errors returned are those of  TStream.ReadStr (296).

     See also:    PutItem (331)



                                                                                 329

                 _______________________________________________________________________________________15.12.___TSTRINGCOLLECTION_*
 *____________________
                 15.12.2         TStringCollection.Compare

Declaration:      Function  TStringCollection.Compare  (Key1,  Key2:    Pointer):    Sw__ Integer;  Virtual;

Description:      TStringCollection overrides the Compare function so it compares the two keys as if they
                 were pointers to strings.  The compare is done case sensitive.  It returns the following results:

                 -1 if the first string is alphabetically earlier than the second string.

                 0if the two strings are equal.

                 1if the first string is alphabetically later than the second string.

       Errors:    None.

     See also:    TSortedCollection.Compare (326)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex37   ;


                 {  Program       to    d e m o n s t r a t et h e  T S t r i n g C o l l e c t i.oCnompare      method     }


                 Uses     O b j e c t s;


                 Var   C   :   P S t r i n g C o l l e c t i;o n
                        S  :   S t r i n g;
                        I  :   l o n g i n t;


                 b e g i n
                    Randomize       ;
                    C := New   ( P S t r i n g C o l l e c t i,oInn i t( 1 2 0 , 1 0 ) ) ;
                    C ^ . D u p l i c a t e:s=True    ;  {   D u p l i c a t e sa l l o w e d}
                    W r i t e l n ( ' I n s e r t i n g|_|1 0 0r|_|e c o r|d_s|a|t_|random  |_|p l a c e.s' ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                        S t r(Random     ( 1 0 0 ) ,S ) ;
                        S:=  ' S t r i n g|_|w i t|h_|v a l u|e_|'+S;
                       C  ^ .I n s e r t(NewStr     (S ) ) ;
                        end  ;
                    For    I :=0    to   9 8  do
                        With    C ^   do
                        I f  Compare       (At  ( i ) ,At  (I +1))=0      then
                           W r i t e l n ( ' D u p l i c a t|e_|s t r i n|g_|f o u n|d_|a|t_|p o s i t i|o_n|',i) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.12.3         TStringCollection.FreeItem

Declaration:      Procedure  TStringCollection.FreeItem  (Item:    Pointer);  Virtual;

Description:      TStringCollection overrides FreeItem so that the string pointed to by Item is disposed
                 from memory.

       Errors:    None.

     See also:    TCollection.FreeItem (320)

                                                                                 330

                 _____________________________________________________________________________________________15.13.___TSTRCOLLECTI*
 *ON__________________
                 15.12.4         TStringCollection.PutItem

Declaration:      Procedure  TStringCollection.PutItem  (Var  S:  TStream;  Item:    Pointer);  Virtual;

Description:      PutItem writes the string pointed to by Item to the stream S.

                 This  method  is  primarily  used  in  the  Load  and  Store  methods,  and  should  not  be  used
                 directly.

       Errors:    Errors are those of  TStream.WriteStr (298).

     See also:    GetItem (329)
                 15.13           TStrCollection


                 The TStrCollection object manages a sorted collection of null-terminated strings (pchar
                 strings).  To this end, it overrides the Compare (326) method of  TSortedCollection, and it
                 introduces methods to read/write strings from a stream.

                 Here is the full declaration of the TStrCollection object:


                 TYPE
                     TStrCollection  =  OBJECT  (TSortedCollection)
                          Function  Compare  (Key1,  Key2:  Pointer):  Sw_Integer;  Virtual;
                          Function  GetItem  (Var  S:  TStream):  Pointer;  Virtual;
                          Procedure  FreeItem  (Item:  Pointer);  Virtual;
                          Procedure  PutItem  (Var  S:  TStream;  Item:  Pointer);  Virtual;
                     END;
                     PStrCollection  =  ^TStrCollection;
                 15.13.1         TStrCollection.GetItem

Declaration:      Function  TStrCollection.GetItem  (Var  S:  TStream):    Pointer;  Virtual;

Description:      GetItem reads a null-terminated string from the stream S and returns a pointer to it.  It
                 doesn't insert the string in the collection.

                 This method is primarily introduced to be able to load and store the collection from and to
                 a stream.

       Errors:    The errors returned are those of  TStream.StrRead (294).

     See also:    PutItem (332)
                 15.13.2         TStrCollection.Compare

Declaration:      Function  TStrCollection.Compare  (Key1,  Key2:    Pointer):    Sw__ Integer;  Virtual;

Description:      TStrCollection overrides the Compare function so it compares the two keys as if they were
                 pointers to strings.  The compare is done case sensitive.  It returns

                 -1 if the first string is alphabetically earlier than the second string.

                 0if the two strings are equal.

                 1if the first string is alphabetically later than the second string.

       Errors:    None.
                                                                                 331

                 _____________________________________________________________________________________________15.13.___TSTRCOLLECTI*
 *ON__________________
     See also:    TSortedCollection.Compare (326)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex38   ;


                 {  Program       to    d e m o n s t r a t et h e T S t r C o l l e c t i o.nCompare      method      }


                 Uses     O b j e c t s,S t r i n g s;


                 Var   C   :   P S t r C o l l e c t i o;n
                        S  :   S t r i n g;
                        I  :   l o n g i n t;
                       P   :   Pchar   ;


                 b e g i n
                    Randomize       ;
                    C := New   ( P S t r C o l l e c t i o,nI n i t( 1 2 0 , 1 0 ) ) ;
                    C ^ . D u p l i c a t e:s=True    ;  {   D u p l i c a t e sa l l o w e d}
                    W r i t e l n ( ' I n s e r t i n g|_|1 0 0r|_|e c o r|d_s|a|t_|random  |_|p l a c e.s' ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                        S t r(Random     ( 1 0 0 ) ,S ) ;
                        S:=  ' S t r i n g|_|w i t|h_|v a l u|e_|'+S;
                       P :=  S t r A l l o c(Length    ( S ) + 1 ) ;
                       C  ^ .I n s e r t(StrPCopy      ( P ,S ) ) ;
                        end  ;
                    For    I :=0    to   9 8  do
                        With    C ^   do
                           I f  Compare       ( At  (I ) ,At  ( I +1))=0      then
                               W r i t e l n( ' D u p l i c a t e|_|s t r i n|g_|f o u n|d_|a|t_|p o s i t i|o_n|',I) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 15.13.3         TStrCollection.FreeItem

Declaration:      Procedure  TStrCollection.FreeItem  (Item:    Pointer);  Virtual;

Description:      TStrCollection overrides FreeItem so that the string pointed to by Item is disposed from
                 memory.

       Errors:    None.

     See also:    TCollection.FreeItem (320)
                 15.13.4         TStrCollection.PutItem

Declaration:      Procedure  TStrCollection.PutItem  (Var  S:  TStream;  Item:    Pointer);  Virtual;

Description:      PutItem writes the string pointed to by Item to the stream S.

                 This  method  is  primarily  used  in  the  Load  and  Store  methods,  and  should  not  be  used
                 directly.

       Errors:    Errors are those of  TStream.StrWrite (298).

     See also:    GetItem (331)


                                                                                 332

                 ___________________________________________________________________________15.14.___TUNSORTEDSTRCOLLECTION________*
 *____________________
                 15.14           TUnSortedStrCollection


                 The TUnSortedStrCollection object manages an unsorted list of objects.  To this end, it
                 overrides the TSortedCollection.Insert (328) method to add strings at the end of the collection,
                 rather than in the alphabetically correct position.

                 Take care, the Search (327) and IndexOf  (313) methods will not work on an unsorted string
                 collection.

                 Here is the full declaration of the TUnsortedStrCollection object:


                 TYPE
                     TUnSortedStrCollection  =  OBJECT  (TStringCollection)
                          Procedure  Insert  (Item:  Pointer);  Virtual;
                     END;
                     PUnSortedStrCollection  =  ^TUnSortedStrCollection;
                 15.14.1         TUnSortedStrCollection.Insert

Declaration:      Procedure  TUnSortedStrCollection.Insert  (Item:    Pointer);  Virtual;

Description:      Insert inserts a string at the end of the collection,  instead of on it's alphabetical place,
                 resulting in an unsorted collection of strings.

       Errors:

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       ex39   ;


                 {  Program       to    d e m o n s t r a t et h e T U n s o r t e d S t r C o l l e c t i.oInn s e r t method     }


                 Uses     O b j e c t s,S t r i n g s;


                 Var   C   :   P U n s o r t e d S t r C o l l e c t i;o n
                        S  :   S t r i n g;
                        I  :   l o n g i n t;
                       P   :   Pchar   ;


                 b e g i n
                    Randomize       ;
                    C := New   ( P U n s o r t e d S t r C o l l e c t i,oInn i t( 1 2 0 , 1 0 ) ) ;
                    W r i t e l n ( ' I n s e r t i n g|_|1 0 0r|_|e c o r|d_s|a|t_|random  |_|p l a c e.s' ) ;
                    For    I :=1    to   1 0 0  do
                        b e g i n
                        S t r(Random     ( 1 0 0 ) ,S ) ;
                        S:=  ' S t r i n g|_|w i t|h_|v a l u|e_|'+S;
                       P :=  S t r A l l o c(Length    ( S ) + 1 ) ;
                       C  ^ .I n s e r t(StrPCopy      ( P ,S ) ) ;
                        end  ;
                    For    I :=0    to   9 9  do
                        W r i t e l n( I : 2 , ' : |_|',PChar   (C ^ . At ( i ) ) ) ;
                    D i s p o s e(C , Done   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 333

                 _________________________________________________________________________________15.15.___TRESOURCECOLLECTION_____*
 *____________________
                 15.15           TResourceCollection


                 A TResourceCollection manages a collection of resource names.  It stores the position and
                 the size of a resource, as well as the name of the resource.  It stores these items in records
                 that look like this:


                 TYPE
                     TResourceItem  =  packed  RECORD
                          Posn:  LongInt;
                          Size:  LongInt;
                          Key  :  String;
                     End;
                     PResourceItem  =  ^TResourceItem;


                 It overrides some methods of  TStringCollection in order to accomplish this.

                 Remark that the TResourceCollection manages the names of the resources and their assi-
                 ciated positions and sizes, it doesn't manage the resources themselves.

                 Here is the full declaration of the TResourceCollection object:


                 TYPE
                     TResourceCollection  =  OBJECT  (TStringCollection)
                          Function  KeyOf  (Item:  Pointer):  Pointer;  Virtual;
                          Function  GetItem  (Var  S:  TStream):  Pointer;  Virtual;
                          Procedure  FreeItem  (Item:  Pointer);  Virtual;
                          Procedure  PutItem  (Var  S:  TStream;  Item:  Pointer);  Virtual;
                     END;
                     PResourceCollection  =  ^TResourceCollection;
                 15.15.1         TResourceCollection.KeyOf

Declaration:      Function  TResourceCollection.KeyOf  (Item:    Pointer):    Pointer;  Virtual;

Description:      KeyOf returns the key of an item in the collection.  For resources, the key is a pointer to
                 the string with the resource name.

       Errors:    None.

     See also:    TStringCollection.Compare (330)
                 15.15.2         TResourceCollection.GetItem

Declaration:      Function  TResourceCollection.GetItem  (Var  S:  TStream):    Pointer;  Virtual;

Description:      GetItem reads a resource item from the stream S. It reads the position, size and name from
                 the stream, in that order.  It DOES NOT read the resource itself from the stream.

                 The resulting item is not inserted in the collection.  This call is manly for internal use by the
                 TCollection.Load (311) method.

       Errors:    Errors returned are those by TStream.Read (299)

     See also:    TCollection.Load (311), TStream.Read (299)
                                                                                 334

                 _______________________________________________________________________________________________15.16.___TRESOURCEF*
 *ILE_________________
                 15.15.3         TResourceCollection.FreeItem

Declaration:      Procedure  TResourceCollection.FreeItem  (Item:    Pointer);  Virtual;

Description:      FreeItem releases the memory occupied by Item.  It de-allocates the name, and then the
                 resourceitem record.

                 It does NOT remove the item from the collection.

       Errors:    None.

     See also:    TCollection.FreeItem (320)
                 15.15.4         TResourceCollection.PutItem

Declaration:      Procedure  TResourceCollection.PutItem  (Var  S:  TStream;  Item:    Pointer);  Virtual;

Description:      PutItem writes Item to the stream S. It does this by writing the position and size and name
                 of the resource item to the stream.

                 This method is used primarily by the Store (323) method.

       Errors:    Errors returned are those by TStream.Write (299).

     See also:    Store (323)
                 15.16           TResourceFile


                 TYPE
                     TResourceFile  =  OBJECT  (TObject)
                               Stream    :  PStream;  {  File  as  a  stream  }
                               Modified:  Boolean;  {  Modified  flag  }
                          Constructor  Init  (AStream:  PStream);
                          Destructor  Done;  Virtual;
                          Function  Count:  Sw_Integer;
                          Function  KeyAt  (I:  Sw_Integer):  String;
                          Function  Get  (Key:  String):  PObject;
                          Function  SwitchTo  (AStream:  PStream;  Pack:  Boolean):  PStream;
                          Procedure  Flush;
                          Procedure  Delete  (Key:  String);
                          Procedure  Put  (Item:  PObject;  Key:  String);
                     END;
                     PResourceFile  =  ^TResourceFile;
                 15.16.1         TResourceFile  Fields

                 TResourceFile has the following fields:


                 Stream      contains the (file) stream that has the executable image and the resources.  It can
                        be initialized by the Init (336) constructor call.

                 Modified       is set to True if one of the resources has been changed.  It is set by the SwitchTo
                        (336), Delete (337) and Put (337) methods.  Calling Flush (337) will clear the Modified
                        flag.


                                                                                 335

                 _______________________________________________________________________________________________15.16.___TRESOURCEF*
 *ILE_________________
                 15.16.2         TResourceFile.Init

Declaration:      Constructor  TResourceFile.Init  (AStream:    PStream);

Description:      Init instantiates a new instance of a TResourceFile object.  If  AStream is not nil then it
                 is considered as a stream describing an executable image on disk.

                 Init  will  try  to  position  the  stream  on  the  start  of  the  resources  section,  and  read  all
                 resources from the stream.

       Errors:    None.

     See also:    Done (336)
                 15.16.3         TResourceFile.Done

Declaration:      Destructor  TResourceFile.Done;  Virtual;

Description:      Done  cleans  up  the  instance  of  the  TResourceFile  Object.   If  Stream  was  specified  at
                 initialization, then Stream is disposed of too.

       Errors:    None.

     See also:    Init (336)
                 15.16.4         TResourceFile.Count

Declaration:      Function  TResourceFile.Count:    Sw__ Integer;

Description:      Count returns the number of resources.  If no resources were read, zero is returned.

       Errors:    None.

     See also:    Init (336)
                 15.16.5         TResourceFile.KeyAt

Declaration:      Function  TResourceFile.KeyAt  (I:  Sw__ Integer):    String;

Description:      KeyAt returns the key (the name) of the I-th resource.

       Errors:    In case I is invalid, TCollection.Error will be executed.

     See also:    Get (336)
                 15.16.6         TResourceFile.Get

Declaration:      Function  TResourceFile.Get  (Key:    String):    PObject;

Description:      Get returns a pointer to a instance of a resource identified by Key.  If  Key cannot be found
                 in the list of resources, then Nil is returned.

       Errors:    Errors returned may be those by TStream.Get

     See also:

                                                                                 336

                 _____________________________________________________________________________________________________15.17.___TSTR*
 *INGLIST_____________
                 15.16.7         TResourceFile.SwitchTo

Declaration:      Function  TResourceFile.SwitchTo  (AStream:    PStream;  Pack:    Boolean):    PStream;

Description:      SwitchTo  switches  to  a  new  stream  to  hold  the  resources  in.   AStream  will  be  the  new
                 stream after the call to SwitchTo.

                 If  Pack is true, then all the known resources will be copied from the current stream to the
                 new stream (AStream).  If  Pack is False, then only the current resource is copied.

                 The return value is the value of the original stream:  Stream.

                 The Modified flag is set as a consequence of this call.

       Errors:    Errors returned can be those of  TStream.Read (299) and TStream.Write (299).

     See also:    Flush (337)
                 15.16.8         TResourceFile.Flush

Declaration:      Procedure  TResourceFile.Flush;

Description:      If the Modified flag is set to True, then Flush writes the resources to the stream Stream.
                 It sets the Modified flag to true after that.

       Errors:    Errors can be those by TStream.Seek (298) and TStream.Write (299).

     See also:    SwitchTo (337)
                 15.16.9         TResourceFile.Delete

Declaration:      Procedure  TResourceFile.Delete  (Key:    String);

Description:      Delete deletes the resource identified by Key from the collection.  It sets the Modified flag
                 to true.

       Errors:    None.

     See also:    Flush (337)
                 15.16.10          TResourceFile.Put

Declaration:      Procedure  TResourceFile.Put  (Item:    PObject;  Key:    String);

Description:      Put  sets  the  resource  identified  by  Key  to  Item.  If  no  such  resource  exists,  a  new  one  is
                 created.  The item is written to the stream.

       Errors:    Errors returned may be those by TStream.Put (297) and TStream.Seek

     See also:    Get (336)
                 15.17           TStringList


                 A  TStringList  object  can  be  used  to  read  a  collection  of  strings  stored  in  a  stream.
                 If  you  register  this  object  with  the  RegisterType  (284)  function,  you  cannot  register  the
                 TStrListMaker object.

                 This is the public declaration of the TStringList object:
                                                                                 337

                 _____________________________________________________________________________________________________15.17.___TSTR*
 *INGLIST_____________
                 TYPE
                     TStrIndexRec  =  Packed  RECORD
                          Key,  Count,  Offset:  Word;
                     END;


                     TStrIndex  =  Array  [0..9999]  Of  TStrIndexRec;
                     PStrIndex  =  ^TStrIndex;


                     TStringList  =  OBJECT  (TObject)
                          Constructor  Load  (Var  S:  TStream);
                          Destructor  Done;  Virtual;
                          Function  Get  (Key:  Sw_Word):  String;
                     END;
                     PStringList  =  ^TStringList;
                 15.17.1         TStringList.Load

Declaration:      Constructor  TstringList.Load  (Var  S:  TStream);

Description:      The Load constructor reads the TStringList object from the stream S. It also reads the
                 descriptions of the strings from the stream.  The string descriptions are stored as an array of
                 TstrIndexrec records, where each record describes a string on the stream.  These records
                 are kept in memory.

       Errors:    If an error occurs, a stream error is triggered.

     See also:    Done (338)
                 15.17.2         TStringList.Done

Declaration:      Destructor  TstringList.Done;  Virtual;

Description:      The  Done  destructor  frees  the  memory  occupied  by  the  string  descriptions,  and  destroys
                 the object.

       Errors:    None.

     See also:    Load (338), TObject.Done (292)
                 15.17.3         TStringList.Get

Declaration:      Function  TStringList.Get  (Key:    Sw__ Word):    String;

Description:      Get reads the string with key Key from the list of strings on the stream, and returns this
                 string.  If there is no string with such a key, an empty string is returned.

       Errors:    If no string with key Key is found, an empty string is returned.  A stream error may result
                 if the stream doesn't contain the needed strings.

     See also:    TStrListMaker.Put (339)

                                                                                 338

                 _______________________________________________________________________________________________15.18.___TSTRLISTMA*
 *KER_________________
                 15.18           TStrListMaker


                 The  TStrListMaker  object  can  be  used  to  generate  a  stream  with  strings,  which  can  be
                 read with the TStringList object.  If you register this object with the RegisterType (284)
                 function, you cannot register the TStringList object.

                 This is the public declaration of the TStrListMaker object:


                 TYPE
                     TStrListMaker  =  OBJECT  (TObject)
                          Constructor  Init  (AStrSize,  AIndexSize:  Sw_Word);
                          Destructor  Done;  Virtual;
                          Procedure  Put  (Key:  SwWord;  S:  String);
                          Procedure  Store  (Var  S:  TStream);
                     END;
                     PStrListMaker  =  ^TStrListMaker;
                 15.18.1         TStrListMaker.Init

Declaration:      Constructor  TStrListMaker.Init  (AStrSize,  AIndexSize:    SwWord);

Description:      The  Init  constructor  creates  a  new  instance  of  the  TstrListMaker  object.   It  allocates
                 AStrSize  bytes  on  the  heap  to  hold  all  the  strings  you  wish  to  store.   It  also  allocates
                 enough room for AIndexSize key description entries (of the type TStrIndexrec).

                 AStrSize must be large enough to contain all the strings you wish to store.  If not enough
                 memory is allocated, other memory will be overwritten.  The same is true for AIndexSize :
                 maximally AIndexSize strings can be written to the stream.

       Errors:    None.

     See also:    TObject.Init (291), Done (339)
                 15.18.2         TStrListMaker.Done

Declaration:      Destructor  TStrListMaker.Done;  Virtual;

Description:      The  Done  destructor  de-allocates  the  memory  for  the  index  description  records  and  the
                 string data, and then destroys the object.

       Errors:    None.

     See also:    TObject.Done (292), Init (339)
                 15.18.3         TStrListMaker.Put

Declaration:      Procedure  TStrListMaker.Put  (Key:    Sw__ Word;  S:  String);

Description:      Put adds they string S with key Key to the collection of strings.  This action doesn't write
                 the string to a stream.  To write the strings to the stream, see the Store (340) method.

       Errors:    None.

     See also:    Store (340).
                                                                                 339

                 _______________________________________________________________________________________________15.18.___TSTRLISTMA*
 *KER_________________
                 15.18.4         TStrListMaker.Store

Declaration:      Procedure  TStrListMaker.Store  (Var  S:  TStream);

Description:      Store writes the collection of strings to the stream S. The collection can then be read with
                 the TStringList object.

       Errors:    A stream error may occur when writing the strings to the stream.

     See also:    TStringList.Load (338), Put (339).



                                                                                 340


Chapter   16


The   PORTS   unit
16.1          Introduction


The ports unit implements the port constructs found in Turbo Pascal.  It uses classes and
default array properties to do this.

The  unit  exists  on  linux,  os/2  and  dos.   It  is  implemented  only  for  compatibility  with
Turbo Pascal.  It's usage is discouraged, because using ports is not portable programming,
and the operating system may not even allow it (for instance Windows 32-bit).

Under linux, your program must be run as root, or the IOPerm call must be set in order to
set appropriate permissions on the port access.
16.2          Types,constants  and  variables



16.2.1        Types

The following types are defined to implement the port access.


tport  =  class
   protected
      procedure  writeport(p  :  longint;data  :  byte);
      function    readport(p  :  longint)  :  byte;
   public
      property  pp[w  :  longint]  :  byte  read  readport  write  writeport;default;
end;


tportw  =  class
   protected
      procedure  writeport(p  :  longint;data  :  word);
      function    readport(p  :  longint)  :  word;
   public
      property  pp[w  :  longint]  :  word  read  readport  write  writeport;default;
end;


tportl  =  class
   Protected
      procedure  writeport(p  :  longint;data  :  longint);
      function    readport(p  :  longint)  :  longint;



                                                            341

_________________________________________________________________16.2.___TYPES,CONSTANTS_AND_VARIABLES_____________________________*
 *___
   Public
    property  pp[w  :  Longint]  :  longint  read  readport  write  writeport;default;
end;


Each of these types allows access to the ports using respectively, a byte, a word or a longint
sized argument.

Since there is a default property for each of this types, a sentence as


   port[221]:=12;


Will result in the byte 12 being written to port 221, if port is defined as a variable of type
tport
16.2.2        variables

The following variables are defined:


port,
portb  :  tport;
portw  :  tportw;
portl  :  tportl;


They allow access to the ports in a Turbo Pascal compatible way.



                                                                342


                 Chapter   17


                 The   PRINTER   unit.



                 This chapter describes the PRINTER unit for Free Pascal.  It was written for dos by Florian
                 kl"ampfl,  and  it  was  written  for  linux  by  Micha"el  Van  Canneyt,  and  has  been  ported  to
                 Windows  32-bit  as  well.  Its  basic  functionality  is  the  same  for  both  systems,  although
                 there are minor differences on linux.

                 The chapter is divided in 2 sections:


                     o  The first section lists types, constants and variables from the interface part of the unit.

                     o  The second section describes the functions defined in the unit.
                 17.1          Types,  Constants  and  variables  :


                 var
                    lst  :  text;


                 Lst is the standard printing device.
                 On linux, Lst is set up using AssignLst('/tmp/PID.lst').  You can change this behaviour
                 at compile time, setting the DefFile constant.
                 17.2          Procedures  and  functions



                 17.2.1        AssignLst

Declaration:      Procedure  AssignLst  (  Var  F  :  text;  ToFile  :    string[255]);

Description:      linux only.
                 Assigns to F a printing device.  ToFile is a string with the following form:

                      o  '|filename  options' :  This sets up a pipe with the program filename, with the given
                       options, such as in the popen() call.

                      o  'filename'  :   Prints  to  file  filename.   Filename  can  contain  the  string  'PID'  (No
                       Quotes), which will be replaced by the PID of your program.  When closing lst, the file
                       will be sent to lpr and deleted.  (lpr should be in PATH)

                      o'filename|' Idem as previous, only the file is NOT sent to lpr, nor is it deleted.  (useful
                       for opening /dev/printer or for later printing)
                                                                             343

            __________________________________________________________________________17.2.___PROCEDURES_AND_FUNCTIONS_____________*
 *_______________
  Errors:    Errors are reported in Linuxerror.

See also:    lpr (1)


           ________________________________________________________________________________________________________________________*
 *________
            program       t e s t p r n;


            u s e s  p r i n t e r;


            v a r  i  :   i n t e g e r;
                   f  :   t e x t;


            b e g i n
               w r i t e l n ( ' T e s t|_|o f|_|p r i n t e|r_|u n i't) ;
               w r i t e l n ( ' W r i t i n g|_|to|_|l s.t. . ') ;
               f o r  i :=1    to   8 0  do    w r i t e l n(  l s t,' T h i s|_|i s|_|l i n|e_|',i, ' . '#13);
               c l o s e (  l s t) ;
               w r i t e l n ( ' Done   . ') ;
               { $ i f d e f l i n u x}
               w r i t e l n ( ' W r i t i n g|_|to|_|p i p.e. . ') ;
                a s s i g n l s t(f , ' | /u s r/ b i n/ l p r|_|-m ') ;
               r e w r i t e ( f ) ;
               f o r  i :=1    to   8 0  do    w r i t e l n( f , ' T h i s|_|i s|_|l i n|e_|',i,' . '#13);
               c l o s e (  f) ;
               w r i t e l n ( ' Done   . ')
               { $ e n d i f}
           _end__._________________________________________________________________________________________________________________*
 *________


                                                                            344


Chapter   18


The   SOCKETS   unit.



This  chapter  describes  the  SOCKETS  unit  for  Free  Pascal.   it  was  written  for  linux  by
Micha"el Van Canneyt, and ported to Windows  32-bit by Florian Klaempfl.  The chapter
is divided in 2 sections:


    o  The first section lists types, constants and variables from the interface part of the unit.

    o  The second section describes the functions defined in the unit.
18.1          Types,  Constants  and  variables  :


The following constants identify the different socket types, as needed in the Socket (355) call.


SOCK_STREAM        =  1;  {  stream  (connection)  socket     }
SOCK_DGRAM          =  2;  {  datagram  (conn.less)  socket    }
SOCK_RAW             =  3;  {  raw  socket                                }
SOCK_RDM             =  4;  {  reliably-delivered  message     }
SOCK_SEQPACKET    =  5;  {  sequential  packet  socket        }
SOCK_PACKET        =10;


The following constants determine the socket domain, they are used in the Socket (355) call.


AF_UNSPEC            =  0;
AF_UNIX               =  1;  {  Unix  domain  sockets                 }
AF_INET               =  2;  {  Internet  IP  Protocol               }
AF_AX25               =  3;  {  Amateur  Radio  AX.25                 }
AF_IPX                 =  4;  {  Novell  IPX                                }
AF_APPLETALK       =  5;  {  Appletalk  DDP                           }
AF_NETROM            =  6;  {  Amateur  radio  NetROM               }
AF_BRIDGE            =  7;  {  Multiprotocol  bridge               }
AF_AAL5               =  8;  {  Reserved  for  Werner's  ATM       }
AF_X25                 =  9;  {  Reserved  for  X.25  project       }
AF_INET6             =  10;  {  IP  version  6                            }
AF_MAX                 =  12;


The following constants determine the protocol family, they are used in the Socket (355) call.


PF_UNSPEC            =  AF_UNSPEC;



                                                            345

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 PF_UNIX               =  AF_UNIX;
                 PF_INET               =  AF_INET;
                 PF_AX25               =  AF_AX25;
                 PF_IPX                 =  AF_IPX;
                 PF_APPLETALK       =  AF_APPLETALK;
                 PF_NETROM            =  AF_NETROM;
                 PF_BRIDGE            =  AF_BRIDGE;
                 PF_AAL5               =  AF_AAL5;
                 PF_X25                 =  AF_X25;
                 PF_INET6             =  AF_INET6;
                 PF_MAX                 =  AF_MAX;


                 The  following  types  are  used  to  store  different  kinds  of  eddresses  for  the  Bind  (348),  Recv
                 (353) and Send (353) calls.


                 TSockAddr  =  packed  Record
                    family:word;
                    data    :array  [0..13]  of  char;
                    end;
                 TUnixSockAddr  =  packed  Record
                    family:word;
                    path:array[0..108]  of  char;
                    end;
                 TInetSockAddr  =  packed  Record
                    family:Word;
                    port    :Word;
                    addr    :Cardinal;
                    pad     :array  [1..8]  of  byte;
                    end;


                 The following type is returned by the SocketPair (355) call.


                 TSockArray  =  Array[1..2]  of  Longint;
                 18.2          Functions  and  Procedures



                 18.2.1        Accept

Declaration:      Function  Accept  (Sock:Longint;Var  Addr;Var  Addrlen:Longint)  :    Longint;

Description:      Accept accepts a connection from a socket Sock, which was listening for a connection.  If a
                 connection is accepted, a file descriptor is returned.  On error -1 is returned.  The returned
                 socket may NOT be used to accept more connections.  The original socket remains open.

                 The  Accept  call  fills  the  address  of  the  connecting  entity  in  Addr,  and  sets  its  length  in
                 Addrlen.   Addr  should  be  pointing  to  enough  space,  and  Addrlen  should  be  set  to  the
                 amount of space available, prior to the call.

       Errors:    On error, -1 is returned, and errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EOPNOTSUPP                  The socket type doesn't support the Listen operation.

                 SYS___EFAULT           Addr points outside your address space.



                                                                                 346

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 SYS___EWOULDBLOCK                     The requested operation would block the process.

     See also:    Listen (352), Connect (349)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       s e r v e r;


                 {
                    Program       to    t e s t S o c k e t s u n i t  by   M i c h a e l van    C a n n e y t and    P e t e r Vre*
 *man
                    S e r v e r  V e r s i o n, F i r s t Run     s o c k __s v rto    l e t  i t  c r e a t e a  s o c k e t and  *
 *   t h e n
                    s o c k __c l i to   c o n n e c t to   t h a t  s o c k e t
                 }


                 u s e s  L i n u x,S o c k e t s;
                 c o n s t
                    SPath    = ' S e r v e r S o'c;


                 Var
                    FromName        :   s t r i n g;
                    B u f f e r     :   s t r i n g[ 2 5 5 ] ;
                    S               :   L o n g i n t;
                    Sin   ,Sout     :  Text   ;


                 p r o c e d u r ep e r r o r ( c o n s t S : s t r i n g) ;
                 b e g i n
                    w r i t e l n ( S , S o c k e t E r r o)r;
                    h a l t( 1 0 0 ) ;
                 end  ;

                 b e g i n
                    S :=  S o c k e t( AF__UNIX     ,SOCK__STREAM        , 0 ) ;
                    i f   S o c k e t E r r o<r>0   then
                      P e r r o r ( ' S e r v e r|_|:S|_|o c k e|t_|: |_|') ;
                    UnLink     (SPath    ) ;
                    i f  not    Bind   ( S , SPath   )   then
                      P E r r o r ( ' S e r v e r|_|:B|_|ind |_|: |_|') ;
                    i f  not     L i s t e n( S , 1 )  then
                      P E r r o r ( ' S e r v e r|_|: |_|L i s t|e_n|: |_|') ;
                    W r i t e l n(' W a i t i n g|_|f o|r_|C o n n e c|t_|from|_|C l i e n,t|_|run |_|now |_|s o c k __c l|i_|i|n_|*
 *an|_|o t h e|r_|t t'y) ;
                    i f  not    A c c e p t ( S , FromName      , Sin  , Sout   )  then
                      P E r r o r ( ' S e r v e r|_|:A|_|c c e p|t_|: |_|'+fromname    ) ;
                    Reset    ( Sin  ) ;
                    ReWrite     ( Sout   ) ;
                    W r i t e l n(Sout   , ' Message     |_|From  |_|S e r v e'r) ;
                    F l u s h( SOut   ) ;
                    w h i l e  not    e o f( s i n)  do
                      b e g i n
                         Readln     ( Sin  , B u f f e r) ;
                          W r i t e l n('S e r v e r|_|: |_|r e a|d_|: |_|',b u f f)e;r
                      end  ;
                    U n l i n k(SPath    ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 18.2.2        Accept

Declaration:      Function  Accept  (Sock:longint;var  addr:string;var  SockIn,SockOut:text)  :    Boolean;



                                                                                 347

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
Description:      This is an alternate form of the Accept (346) command.  It is equivalent to subsequently
                 calling  the  regular  Accept  (346)  function  and  the  Sock2Text  (355)  function.  The  function
                 returns True if successfull, False otherwise.

       Errors:    The errors are those of  Accept (346).

     See also:    Accept (346)
                 18.2.3        Accept

Declaration:      Function  Accept  (Sock:longint;var  addr:string;var  SockIn,SockOut:File)  :    Boolean;

Description:      This is an alternate form of the Accept (346) command.  It is equivalent to subsequently
                 calling the regular Accept (346) function and the Sock2File (354) function.  The Addr param-
                 eter contains the name of the unix socket file to be opened.  The function returns True if
                 successfull, False otherwise.

       Errors:    The errors are those of  Accept (346).

     See also:    Accept (346)
                 18.2.4        Accept

Declaration:      Function  Accept  (Sock:longint;var  addr:TInetSockAddr;var  SockIn,SockOut:File)
                 :    Boolean;

Description:      This is an alternate form of the Accept (346) command.  It is equivalent to subsequently
                 calling  the  regular  Accept  (346)  function  and  the  Sock2File  (354)  function.  The  Addr  pa-
                 rameter contains the parameters of the internet socket that should be opened.  The function
                 returns True if successfull, False otherwise.

       Errors:    The errors are those of  Accept (346).

     See also:    Accept (346)
                 18.2.5        Bind

Declaration:      Function  Bind  (Sock:Longint;Var  Addr;AddrLen:Longint)  :    Boolean;

Description:      Bind binds the socket Sock to address Addr.  Addr has length Addrlen.  The function returns
                 True if the call was succesful, False if not.

       Errors:    Errors are returned in SocketError and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___EINVAL           The socket is already bound to an address,

                 SYS___EACCESS            Address is protected and you don't have permission to open it.

                 More arrors can be found in the Unix man pages.

     See also:    Socket (355)
                                                                                 348

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 18.2.6        Bind

Declaration:      Function  Bind  (Sock:longint;const  addr:string)  :    boolean;

Description:      This is an alternate form of the Bind command.  This form of the Bind command is equiv-
                 alent  to  subsequently  calling  Str2UnixSockAddr  (355)  and  the  regular  Bind  (348)  function.
                 The function returns True if successfull, False otherwise.

       Errors:    Errors are those of the regular Bind (348) command.

     See also:    Bind (348)
                 18.2.7        Connect

Declaration:      Function  Connect  (Sock:Longint;Var  Addr;Addrlen:Longint)  :    Longint;

Description:      Connect  opens  a  connection  to  a  peer,  whose  address  is  described  by  Addr.   AddrLen
                 contains  the  length  of  the  address.  The  type  of  Addr  depends  on  the  kind  of  connection
                 you're trying to make, but is generally one of  TSockAddr or TUnixSockAddr.

                 The Connect function returns a file descriptor if the call was successfull, -1 in case of error.

       Errors:    On error, -1 is returned and errors are reported in SocketError.

     See also:    Listen (352), Bind (348),Accept (346)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       C l i e n t;


                 {
                    Program       to    t e s t S o c k e t s u n i t  by   M i c h a e l van    C a n n e y t and    P e t e r Vre*
 *man
                    C l i e n t  V e r s i o n, F i r s t Run     s o c k __s v rto    l e t  i t  c r e a t e a  s o c k e t and  *
 *   t h e n
                    s o c k __c l i to   c o n n e c t to   t h a t  s o c k e t
                 }


                 u s e s  S o c k e t s,L i n u x;


                 p r o c e d u r eP E r r o r(c o n s t  S  :   s t r i n g) ;
                 b e g i n
                    w r i t e l n(S , S o c k e t E r r o)r;
                    h a l t( 1 0 0 ) ;
                 end  ;



                 Var
                    Saddr           :   S t r i n g[ 2 5 ] ;
                    B u f f e r     :   s t r i n g [ 2 5 5 ] ;
                    S               :   L o n g i n t;
                    Sin   ,Sout     :  Text   ;
                    i               :   i n t e g e r;
                 b e g i n
                    S :=  S o c k e t( AF__UNIX     ,SOCK__STREAM        , 0 ) ;
                    i f   S o c k e t E r r o<r>0   then
                      P e r r o r(' C l i e n t|_|: |_|S o c k|e_t|: |_|') ;
                    Saddr    :=  'S e r v e r S o c';
                    i f  not    C o n n e c t ( S , SAddr   , Sin  , Sout   )  then
                      P E r r o r(' C l i e n t|_|: |_|C o n n e|c_t|: |_|') ;
                    Reset    ( Sin  ) ;
                    ReWrite     ( Sout   ) ;
                                                                                 349

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                    B u f f e r:= ' T h i s|_|i s|_|a|_|t e x t s t r i|n_g|s e n|t_|by|_|t h|e_|C l i e.n't;
                    f o r  i :=1    to   1 0  do
                      W r i t e l n(Sout   , B u f f e r) ;
                    F l u s h( Sout   ) ;
                    Readln     (SIn   , B u f f e r) ;
                    WriteLn     ( B u f f e r) ;
                    C l o s e( s o u t) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 18.2.8        Connect

Declaration:      Function  Connect  (Sock:longint;const  addr:string;var  SockIn,SockOut:text)  :    Boolean;

Description:      This is an alternate form of the Connect (349) command.  It is equivalent to subsequently
                 calling the regular Connect (349) function and the Sock2Text (355) function.  The function
                 returns True if successfull, False otherwise.

       Errors:    The errors are those of  Connect (349).

     See also:    Connect (349)
                 18.2.9        Connect

Declaration:      Function  Connect  (Sock:longint;const  addr:string;var  SockIn,SockOut:file)  :    Boolean;

Description:      This  is  an  alternate  form  of  the  Connect  (349)  command.  The  parameter  addr  contains
                 the name of the unix socket file to be opened.  It is equivalent to subsequently calling the
                 regular Connect (349) function and the Sock2File (354) function.  The function returns True
                 if successfull, False otherwise.

       Errors:    The errors are those of  Connect (349).

     See also:    Connect (349)
                 18.2.10         Connect

Declaration:      Function  Connect  (Sock:longint;const  addr:    TInetSockAddr;var  SockIn,SockOut:file)
                 :    Boolean;

Description:      This  is  another  alternate  form  of  the  Connect  (349)  command.  It  is  equivalent  to  subse-
                 quently  calling  the  regular  Connect  (349)  function  and  the  Sock2File  (354)  function.  The
                 Addr parameter contains the parameters of the internet socket to connect to.  The function
                 returns True if successfull, False otherwise.

       Errors:    The errors are those of  Connect (349).

     See also:    Connect (349)


                ___________________________________________________________________________________________________________________*
 *_____________
                 program       p f i n g e r;


                 u s e s  s o c k e t s,e r r o r s;


                 Var    Addr    :   T I n e t S o c k A d d;r
                  S   :   L o n g i n t;
                        Sin  , Sout    :   Text   ;
                                                                                 350

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                        L i n e :   s t r i n g;


                 b e g i n
                    Addr   . f a m i l y:= AF__INET    ;
                    {   p o r t 7 9   i n  n e t w o r k o r d e r }
                    Addr   . p o r t: = 7 9  s h l 8 ;
                    {   l o c a l h o s t:  1 2 7 . 0 . 0 . 1 i n  n e t w o r k o r d e r }
                    Addr   . addr   : = ( ( 1  s h l 2 4 )  or   1 2 7 ) ;
                    S :=  S o c k e t(AF__INET    ,SOCK__STREAM        , 0 ) ;
                    I f  Not    C o n n e c t ( S ,ADDR    ,SIN   ,SOUT   )   Then
                        b e g i n
                        W r i t e l n( ' Couldn     '' t |_|c o n n e c|t_|to|_|l o c a l h o s't) ;
                        W r i t e l n( ' S o c k e t|_|e r r o|r_|: |_|',s t r e r r o(rS o c k e t E r r o)r) ;
                        h a l t( 1 ) ;
                        end  ;
                    r e w r i t e ( s o u t) ;
                    r e s e t( s i n) ;
                    w r i t e l n ( s o u t, p a r a m s t r( 1 ) ) ;
                    f l u s h( s o u t) ;
                    w h i l e  not    e o f( s i n)  do
                        b e g i n
                        r e a d l n ( Sin  , l i n e) ;
                        w r i t e l n(  l i n e) ;
                        end  ;
                    Shutdown      ( s , 2 ) ;
                    c l o s e (  s i n) ;
                    c l o s e (  s o u t) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 18.2.11         GetPeerName

Declaration:      Function  GetPeerName  (Sock:Longint;Var  Addr;Var  Addrlen:Longint)  :    Longint;

Description:      GetPeerName returns the name of the entity connected to the specified socket Sock.  The
                 Socket must be connected for this call to work.  Addr should point to enough space to store
                 the  name,  the  amount  of  space  pointed  to  should  be  set  in  Addrlen.  When  the  function
                 returns succesfully, Addr will be filled with the name, and Addrlen will be set to the length
                 of  Addr.

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOBUFS             The system doesn't have enough buffers to perform the operation.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EFAULT           Addr points outside your address space.

                 SYS___ENOTCONN                The socket isn't connected.

     See also:    Connect (349), Socket (355), connect (2)
                 18.2.12         GetSocketName

Declaration:      Function  GetSocketName  (Sock:Longint;Var  Addr;Var  Addrlen:Longint)  :    Longint;

Description:      GetSockName returns the current name of the specified socket Sock.  Addr should point to
                 enough space to store the name, the amount of space pointed to should be set in Addrlen.



                                                                                 351

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 When the function returns succesfully, Addr will be filled with the name, and Addrlen will
                 be set to the length of  Addr.

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOBUFS             The system doesn't have enough buffers to perform the operation.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EFAULT           Addr points outside your address space.

     See also:    Bind (348)
                 18.2.13         GetSocketOptions

Declaration:      Function  GetSocketOptions  (Sock,Level,OptName:Longint;Var  OptVal;optlen:longint)
                 :    Longint;

Description:      GetSocketOptions gets the connection options for socket Sock.  The socket may be obtained
                 from different levels, indicated by Level, which can be one of the following:

                 SOL___SOCKET            From the socket itself.

                 XXX     set  Level  to  XXX,  the  protocol  number  of  the  protocol  which  should  interprete  the
                       option.

                 For more information on this call, refer to the unix manual page getsockopt (2) .

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EFAULT           OptVal points outside your address space.

     See also:    GetSocketOptions (352)
                 18.2.14         Listen

Declaration:      Function  Listen  (Sock,MaxConnect:Longint)  :    Boolean;

Description:      Listen listens for up to MaxConnect connections from socket Sock.  The socket Sock must
                 be of type SOCK__ STREAM or Sock__ SEQPACKET. The function returns True if a connection was
                 accepted, False if an error occurred.

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EOPNOTSUPP                  The socket type doesn't support the Listen operation.

     See also:    Socket (355), Bind (348), Connect (349)

                                                                                 352

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 18.2.15         Recv

Declaration:      Function  Recv  (Sock:Longint;Var  Addr;AddrLen,Flags:Longint)  :    Longint;

Description:      Recv reads at most Addrlen bytes from socket Sock into address Addr.  The socket must
                 be in a connected state.  Flags can be one of the following:

                 1:  Process out-of band data.

                 4:  Bypass routing, use a direct interface.

                 ?? :  Wait for full request or report an error.

                 The functions returns the number of bytes actually read from the socket, or -1 if a detectable
                 error occurred.

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTCONN                The socket isn't connected.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EFAULT           The address is outside your address space.

                 SYS___EMSGSIZE             The message cannot be sent atomically.

                 SYS___EWOULDBLOCK                     The requested operation would block the process.

                 SYS___ENOBUFS             The system doesn't have enough free buffers available.

     See also:    Send (353)
                 18.2.16         Send

Declaration:      Function  Send  (Sock:Longint;Var  Addr;AddrLen,Flags:Longint)  :    Longint;

Description:      Send sends AddrLen bytes starting from address Addr to socket Sock.  Sock must be in a
                 connected state.  The function returns the number of bytes sent, or -1 if a detectable error
                 occurred.  Flags can be one of the following:

                 1:  Process out-of band data.

                 4:  Bypass routing, use a direct interface.

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EFAULT           The address is outside your address space.

                 SYS___EMSGSIZE             The message cannot be sent atomically.

                 SYS___EWOULDBLOCK                     The requested operation would block the process.

                 SYS___ENOBUFS             The system doesn't have enough free buffers available.

     See also:    Recv (353), send (2)


                                                                                 353

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 18.2.17         SetSocketOptions

Declaration:      Function  SetSocketOptions  (Sock,Level,OptName:Longint;Var  OptVal;optlen:longint)
                 :    Longint;

Description:      SetSocketOptions sets the connection options for socket Sock.  The socket may be manip-
                 ulated at different levels, indicated by Level, which can be one of the following:

                 SOL___SOCKET            To manipulate the socket itself.

                 XXX     set  Level  to  XXX,  the  protocol  number  of  the  protocol  which  should  interprete  the
                       option.

                 For more information on this call, refer to the unix manual page setsockopt (2) .

       Errors:    Errors are reported in SocketError, and include the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTSOCK               The descriptor is not a socket.

                 SYS___EFAULT           OptVal points outside your address space.

     See also:    GetSocketOptions (352)
                 18.2.18         Shutdown

Declaration:      Function  Shutdown  (Sock:Longint;How:Longint)  :    Longint;

Description:      ShutDown closes one end of a full duplex socket connection, described by Sock.  How deter-
                 mines how the connection will be shut down, and can be one of the following:

                 0:  Further receives are disallowed.

                 1:  Further sends are disallowed.

                 2:  Sending nor receiving are allowed.

                 On succes, the function returns 0, on error -1 is returned.

       Errors:    SocketError is used to report errors, and includes the following:

                 SYS___EBADF           The socket descriptor is invalid.

                 SYS___ENOTCONN                The socket isn't connected.

                 SYS___ENOTSOCK               The descriptor is not a socket.

     See also:    Socket (355), Connect (349)
                 18.2.19         Sock2File

Declaration:      Procedure  Sock2File  (Sock:Longint;Var  SockIn,SockOut:File);

Description:      Sock2File  transforms  a  socket  Sock  into  2  Pascal  file  descriptors  of  type  File,  one  for
                 reading from the socket (SockIn), one for writing to the socket (SockOut).

       Errors:    None.

     See also:    Socket (355), Sock2Text (355)

                                                                                 354

                 __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES________*
 *____________________
                 18.2.20         Sock2Text

Declaration:      Procedure  Sock2Text  (Sock:Longint;Var  SockIn,SockOut:    Text);

Description:      Sock2Text  transforms  a  socket  Sock  into  2  Pascal  file  descriptors  of  type  Text,  one  for
                 reading from the socket (SockIn), one for writing to the socket (SockOut).

       Errors:    None.

     See also:    Socket (355), Sock2File (354)
                 18.2.21         Socket

Declaration:      Function  Socket  (Domain,SocketType,Protocol:Longint)  :    Longint;

Description:      Socket  creates  a  new  socket  in  domain  Domain,  from  type  SocketType  using  protocol
                 Protocol.  The Domain, Socket type and Protocol can be specified using predefined constants
                 (see  the  section  on  constants  for  available  constants)  If  succesfull,  the  function  returns  a
                 socket descriptor, which can be passed to a subsequent Bind (348) call.  If unsuccesfull, the
                 function returns -1.

       Errors:    Errors are returned in SocketError, and include the follwing:

                 SYS___EPROTONOSUPPORT                          The  protocol  type  or  the  specified  protocol  is  not  sup-
                       ported within this domain.

                 SYS___EMFILE           The per-process descriptor table is full.

                 SYS___ENFILE          The system file table is full.

                 SYS___EACCESS            Permission  to  create  a  socket  of  the  specified  type  and/or  protocol  is
                       denied.

                 SYS___ENOBUFS             Insufficient buffer space is available.  The socket cannot be created until
                       sufficient resources are freed.

     See also:    SocketPair (355), socket (2)


                 for an example, see Accept (346).
                 18.2.22         SocketPair

Declaration:      Function  SocketPair  (Domain,SocketType,Protocol:Longint;var  Pair:TSockArray)
                 :    Longint;

Description:      SocketPair creates 2 sockets in domain Domain, from type SocketType and using protocol
                 Protocol.  The pair is returned in Pair, and they are indistinguishable.  The function returns
                 -1 upon error and 0 upon success.

       Errors:    Errors are reported in SocketError, and are the same as in Socket (355)

     See also:    Str2UnixSockAddr (355)
                 18.2.23         Str2UnixSockAddr

Declaration:      Procedure  Str2UnixSockAddr(const  addr:string;var  t:TUnixSockAddr;var  len:longint)

Description:      Str2UnixSockAddr transforms a Unix socket address in a string to a TUnixSockAddr struc-
                 ture which can be passed to the Bind (348) call.



                                                                                 355

            __________________________________________________________________________18.2.___FUNCTIONS_AND_PROCEDURES_____________*
 *_______________
  Errors:    None.

See also:    Socket (355), Bind (348)

                                                                            356


                 Chapter   19


                 The   STRINGS   unit.



                 This chapter describes the STRINGS unit for Free Pascal.  This unit is system independent,
                 and therefore works on all supported platforms.

                 Since the unit only provides some procedures and functions, there is only one section, which
                 gives the declarations of these functions, together with an explanation.
                 19.1          Functions  and  procedures.



                 19.1.1        StrAlloc

Declaration:      Function  StrAlloc  (Len  :    Longint);PChar

Description:      StrAlloc  reserves  memory  on  the  heap  for  a  string  with  length  Len,  terminating  #0  in-
                 cluded, and returns a pointer to it.

       Errors:    If there is not enough memory, a run-time error occurs.

     See also:    StrNew (364), StrPCopy (365).
                 19.1.2        StrCat

Declaration:      Function  StrCat  (Dest,Source  :    PChar)  :    PChar;

Description:      Attaches Source to Dest and returns Dest.

       Errors:    No length checking is performed.

     See also:    Concat ()


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example11      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r C a t  f u n c t i o n.  }


                 Const     P1   :   PChar     =   ' T h i s|_|i s|_|a|_|PChar |_|S t r i n.g' ;


                 Var    P2   :  PChar    ;

                                                                             357

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                 b e g i n
                    P2  := S t r A l l o c ( StrLen    ( P1 ) * 2 + 1 ) ;
                    StrMove       ( P2 , P1  ,StrLen     (P1  ) + 1 ) ;  {  P2 = P1   }
                    StrCat      ( P2  ,P1  ) ;                           {  Append      P2   once     more    }
                    W r i t e l n ( 'P2   |_|: |_|',P2) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.3        StrComp

Declaration:      Function  StrComp  (S1,S2  :    PChar)  :    Longint;

Description:      Compares the null-terminated strings S1 and S2.  The result is

                      oA negative Longint when S1<S2.

                      o0 when S1=S2.

                      oA positive Longint when S1>S2.

       Errors:    None.

     See also:    StrLComp (361), StrIComp (360), StrLIComp (363)


                 For an example, see StrLComp (361).
                 19.1.4        StrCopy

Declaration:      Function  StrCopy  (Dest,Source  :    PChar)  :    PChar;

Description:      Copy the null terminated string in Source to Dest, and returns a pointer to Dest.  Dest
                 needs enough room to contain Source, i.e.  StrLen(Source)+1 bytes.

       Errors:    No length checking is performed.

     See also:    StrPCopy (365), StrLCopy (362), StrECopy (359)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example4      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r C o p y f u n c t i o n.  }


                 Const     P   :  PCHar     =   ' T h i s|_|i s|_|a|_|PCHAR |_|s t r i n.g' ;


                 v a r PP    :  PChar    ;


                 b e g i n
                    PP  := S t r A l l o c(S t r l e n(P ) + 1 ) ;
                    STrCopy       ( PP , P ) ;
                    I f  StrComp       ( PP  ,P )<>0     then
                        W r i t e l n( ' Oh - oh  |_|p r o b l e m.s. . ')
                    e l s e
                        W r i t e l n( ' A l l|_|i s|_|w e l l|_|:P|_|P=',PP  ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 358

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                 19.1.5        StrDispose

Declaration:      Procedure  StrDispose  (P  :  PChar);

Description:      Removes the string in P from the heap and releases the memory.

       Errors:    None.

     See also:    Dispose () , StrNew (364)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example17      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r D i s p o s e f u n c t i o n.  }


                 Const     P1   :   PChar     =   ' T h i s|_|i s|_|a|_|PChar |_|s t r i n'g;


                 v a r  P2   :  PChar    ;


                 b e g i n
                    W r i t e l n ( ' B e f o r e|_|StnNew   |_|:M|_|emory  |_|a v a i l a b l|e_|: |_|',MemAvail   ) ;
                    P2  := StrNew      ( P1  ) ;
                    W r i t e l n ( ' A f t e r|_|StrNew   |_|: |_|Memory |_|a v a i l a b l|e_|: |_|',MemAvail    ) ;
                    W r i t e l n ( 'P2   |_|: |_|',P2) ;
                    S t r D i s p o s e(P2 ) ;
                    W r i t e l n ( ' A f t e r|_|S t r D i s p o s|e_|:M|_|emory|_|a v a i l a b l|e_|: |_|',MemAvail   ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.6        StrECopy

Declaration:      Function  StrECopy  (Dest,Source  :    PChar)  :    PChar;

Description:      Copies the Null-terminated string in Source to Dest, and returns a pointer to the end (i.e.
                 the terminating Null-character) of the copied string.

       Errors:    No length checking is performed.

     See also:    StrLCopy (362), StrCopy (358)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e StrECopy        f u n c t i o n.  }


                 Const     P   :  PChar     =   ' T h i s|_|i s|_|a|_|PCHAR |_|s t r i n.g' ;


                 Var   PP    :  PChar    ;


                 b e g i n
                    PP  := S t r A l l o c ( StrLen    ( P ) + 1 ) ;
                    I f   L o n g i n t(StrECopy     ( PP  ,P ))-  L o n g i n t(PP )<>   StrLen    ( P )  then
                        W r i t e l n('S o m e t h i n g|_|i|s_|wrong  |_|h e r e|_|!)'
                    e l s e
                        W r i t e l n( ' PP  = |_|',PP ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 359

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                 19.1.7        StrEnd

Declaration:      Function  StrEnd  (P  :  PChar)  :    PChar;

Description:      Returns a pointer to the end of  P. (i.e.  to the terminating null-character.

       Errors:    None.

     See also:    StrLen (362)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r E n d  f u n c t i o n.  }


                 Const     P   :  PChar     =   ' T h i s|_|i s|_|a|_|PCHAR |_|s t r i n.g' ;


                 b e g i n
                    I f   L o n g i n t(StrEnd    (P ))-   L o n g i n t(P)<>   StrLen    (P  )  then
                        W r i t e l n('S o m e t h i n g|_|i|s_|wrong  |_|h e r e|_|!)'
                    e l s e
                        W r i t e l n( ' A l l|_|i s|_|w e l l. . ') ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.8        StrIComp

Declaration:      Function  StrIComp  (S1,S2  :    PChar)  :    Longint;

Description:      Compares the null-terminated strings S1 and S2, ignoring case.  The result is

                      oA negative Longint when S1<S2.

                      o0 when S1=S2.

                      oA positive Longint when S1>S2.

       Errors:    None.

     See also:    StrLComp (361), StrComp (358), StrLIComp (363)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e StrLComp        f u n c t i o n.  }


                 Const     P1   :   PChar     =   ' T h i s|_|i s|_|t h|e_|f i r s|t_|s t r i n.g';
                           P2   :   PCHar     =   ' T h i s|_|i s|_|t h|e_|s e c o n|d_|s t r i.n'g;


                 Var    L  :   L o n g i n t;


                 b e g i n
                    Write     (  'P1  |_|and |_|P2|_|a r e|_|') ;
                    I f  StrComp       ( P1  ,P2  )<>0     then    w r i t e (  'NOT   |_|') ;
                    w r i t e (  'e q u a l. |_|The |_|f i r s|t_|') ;
                    L : = 1 ;
                    While      StrLComp      (P1  ,P2  , L )=0   do    i n c ( L ) ;



                                                                                 360

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                    dec  ( l ) ;
                    W r i t e l n ( l , ' |_|c h a r a c t e|r_s|a r|e_|t h|e_|same. ' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.9        StrLCat

Declaration:      Function  StrLCat  (Dest,Source  :    PChar;  MaxLen  :    Longint)  :    PChar;

Description:      Adds MaxLen characters from Source to Dest, and adds a terminating null-character.  Re-
                 turns Dest.

       Errors:    None.

     See also:    StrCat (357)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example12      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r L C a t f u n c t i o n.  }


                 Const     P1   :   PChar     =   ' 1 2 3 4 5 6 7 8 9 0;'


                 Var    P2   :  PChar    ;


                 b e g i n
                    P2  := S t r A l l o c ( StrLen    ( P1 ) * 2 + 1 ) ;
                    P2  ^:=#0;      {  Zero     l e n g t h }
                    StrCat      ( P2  ,P1  ) ;
                    StrLCat       ( P2 , P1  , 5 ) ;
                    W r i t e l n ( 'P2  |_|= |_|',P2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.10         StrLComp

Declaration:      Function  StrLComp  (S1,S2  :    PChar;  L  :  Longint)  :    Longint;

Description:      Compares maximum L characters of the null-terminated strings S1 and S2.  The result is

                      oA negative Longint when S1<S2.

                      o0 when S1=S2.

                      oA positive Longint when S1>S2.

       Errors:    None.

     See also:    StrComp (358), StrIComp (360), StrLIComp (363)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e StrLComp        f u n c t i o n.  }


                 Const     P1   :   PChar     =   ' T h i s|_|i s|_|t h|e_|f i r s|t_|s t r i n.g';



                                                                                 361

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                           P2   :   PCHar     =   ' T h i s|_|i s|_|t h|e_|s e c o n|d_|s t r i.n'g;


                 Var    L  :   L o n g i n t;


                 b e g i n
                    Write     (  'P1  |_|and |_|P2|_|a r e|_|') ;
                    I f  StrComp       ( P1  ,P2  )<>0     then    w r i t e (  'NOT   |_|') ;
                    w r i t e (  'e q u a l. |_|The |_|f i r s|t_|') ;
                    L : = 1 ;
                    While      StrLComp      (P1  ,P2  , L )=0   do    i n c ( L ) ;
                    dec  ( l ) ;
                    W r i t e l n ( l , ' |_|c h a r a c t e|r_s|a r|e_|t h|e_|same. ' ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.11         StrLCopy

Declaration:      Function  StrLCopy  (Dest,Source  :    PChar;  MaxLen  :    Longint)  :    PChar;

Description:      Copies MaxLen characters from Source to Dest, and makes Dest a null terminated string.

       Errors:    No length checking is performed.

     See also:    StrCopy (358), StrECopy (359)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example5      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r L C o p y f u n c t i o n.  }


                 Const     P   :  PCHar     =   ' 1 2 3 4 5 6 7 8A9BCDEF    ' ;


                 v a r PP    :  PCHar    ;


                 b e g i n
                    PP  := S t r A l l o c( 1 1 ) ;
                    W r i t e l n ( ' F i r s t|_|10 |_|c h a r a c t e|r_s|o|f_|P|_|: |_|',StrLCopy    (PP  , P , 1 0 ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.12         StrLen

Declaration:      Function  StrLen  (p  :    PChar)  :    Longint;

Description:      Returns the length of the null-terminated string P.

       Errors:    None.

     See also:    Length ()


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r L e n  f u n c t i o n.  }

                                                                                 362

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                 Const     P   :  PChar     =   ' T h i s|_|i s|_|a|_|c o n s t a|n_t|p c h a|r_|s t r i'n;g


                 b e g i n
                    W r i t e l n ( 'P  |_||_||_||_||_||_||_||_||_|:,|_|'p) ;
                    W r i t e l n ( ' l e n g t h(P ) |_|: |_|',StrLen   (P ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.13         StrLIComp

Declaration:      Function  StrLIComp  (S1,S2  :    PChar;  L  :  Longint)  :    Longint;

Description:      Compares maximum L characters of the null-terminated strings S1 and S2, ignoring case.
                 The result is

                      oA negative Longint when S1<S2.

                      o0 when S1=S2.

                      oA positive Longint when S1>S2.

       Errors:    None.

     See also:    StrLComp (361), StrComp (358), StrIComp (360)


                 For an example, see StrIComp (360)
                 19.1.14         StrLower

Declaration:      Function  StrLower  (P  :  PChar)  :    PChar;

Description:      Converts P to an all-lowercase string.  Returns P.

       Errors:    None.

     See also:    Upcase () , StrUpper (367)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example14      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r L o w e r and    S t r U p p e r f u n c t i o n s.  }


                 Const
                        P1   :  PChar     =   ' THIS   |_|I S|_|AN|_|UPPERCASE     |_|PCHAR   |_|STRING   ';
                        P2   :  PChar     =   ' t h i s|_|i s|_|a|_|l o w e r c a|s_e|s t r i n'g;


                 b e g i n
                    W r i t e l n ( ' U p p e r c a s e|_|: |_|',StrUpper   ( P2 ) ) ;
                    StrLower        (P1  ) ;
                    W r i t e l n ( ' L o w e r c a s e|_|: |_|',P1) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.15         StrMove

Declaration:      Function  StrMove  (Dest,Source  :    PChar;  MaxLen  :    Longint)  :    PChar;

                                                                                 363

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
Description:      Copies MaxLen characters from Source to Dest.  No terminating null-character is copied.
                 Returns Dest.

       Errors:    None.

     See also:    StrLCopy (362), StrCopy (358)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e StrMove       f u n c t i o n.  }


                 Const     P1   :   PCHAR     =   ' T h i s|_|i s|_|a|_|p c h a|r_|s t r i.n'g;



                 Var    P2   :  Pchar    ;


                 b e g i n
                    P2  := S t r A l l o c(StrLen    ( P1  ) + 1 ) ;
                    StrMove       ( P2 , P1  ,StrLen     (P1  ) + 1 ) ;  {  P2 :=  P1   }
                    W r i t e l n ( 'P2  |_|= |_|',P2 ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.16         StrNew

Declaration:      Function  StrNew  (P  :  PChar)  :    PChar;

Description:      Copies P to the Heap, and returns a pointer to the copy.

       Errors:    Returns Nil if no memory was available for the copy.

     See also:    New () , StrCopy (358), StrDispose (359)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example16      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e StrNew       f u n c t i o n.  }


                 Const     P1   :   PChar     =   ' T h i s|_|i s|_|a|_|PChar |_|s t r i n'g;


                 v a r  P2   :  PChar    ;


                 b e g i n
                    P2  := StrNew      ( P1  ) ;
                    I f  P1  = P2   then
                        w r i t e l n( ' T h i s|_|can ' ' t|_|be |_|h a p p e n i n.g. . ')
                    e l s e
                        w r i t e l n( ' P2  |_|: |_|',P2) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.17         StrPas

Declaration:      Function  StrPas  (P  :  PChar)  :    String;



                                                                                 364

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
Description:      Converts a null terminated string in P to a Pascal string, and returns this string.  The string
                 is truncated at 255 characters.

       Errors:    None.

     See also:    StrPCopy (365)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example3      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r P a s  f u n c t i o n.  }


                 Const     P   :  PChar     =   ' T h i s|_|i s|_|a|_|PCHAR |_|s t r i n'g;


                 v a r  S  :   s t r i n g;


                 b e g i n
                    S := StrPas      ( P ) ;
                    W r i t e l n ( 'S  |_|: |_|',S) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.18         StrPCopy

Declaration:      Function  StrPCopy  (Dest  :    PChar;  Const  Source  :    String)  :    PChar;

Description:      Converts  the  Pascal  string  in  Source  to  a  Null-terminated  string,  and  copies  it  to  Dest.
                 Dest needs enough room to contain the string Source, i.e.  Length(Source)+1 bytes.

       Errors:    No length checking is performed.

     See also:    StrPas (364)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example2      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e StrPCopy        f u n c t i o n.  }


                 Const     S  =   ' T h i s|_|i s|_|a|_|n o r m a|l_|s t r i.n'g;


                 Var   P   :   Pchar   ;


                 b e g i n
                    p :=  S t r A l l o c( l e n g t h(S ) + 1 ) ;
                    i f  StrPCopy        ( P ,S )<>  P   then
                        W r i t e l n( ' T h i s|_|i s|_|i m p o s s i b l|e_|!)! '
                    e l s e
                        w r i t e l n( P ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.19         StrPos

Declaration:      Function  StrPos  (S1,S2  :    PChar)  :    PChar;
                                                                                 365

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
Description:      Returns a pointer to the first occurrence of  S2 in S1.  If  S2 does not occur in S1, returns
                 Nil.

       Errors:    None.

     See also:    Pos () , StrScan (366), StrRScan (366)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example15      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r P o s  f u n c t i o n.  }


                 Const     P   :  PChar     =   ' T h i s|_|i s|_|a|_|PChar |_|s t r i n.g' ;
                           S   :  Pchar     =   ' i s' ;
                 b e g i n
                    W r i t e l n ( ' P o s i t i o n|_|o|f_|''i s'' |_|i n|_|P|_|: |_|',l o n g i n(tStrPos   (P , S ))-  L o n g *
 *i n t(P ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 19.1.20         StrRScan

Declaration:      Function  StrRScan  (P  :  PChar;  C  :  Char)  :    PChar;

Description:      Returns a pointer to the last occurrence of the character C in the null-terminated string P.
                 If  C does not occur, returns Nil.

       Errors:    None.

     See also:    Pos () , StrScan (366), StrPos (365)


                 For an example, see StrScan (366).
                 19.1.21         StrScan

Declaration:      Function  StrScan  (P  :  PChar;  C  :  Char)  :    PChar;

Description:      Returns a pointer to the first occurrence of the character C in the null-terminated string P.
                 If  C does not occur, returns Nil.

       Errors:    None.

     See also:    Pos () , StrRScan (366), StrPos (365)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example13      ;


                 Uses     s t r i n g s;


                 {  Program       to    d e m o n s t r a t et h e S t r S c a n and    S t r R S c a n f u n c t i o n s.  }


                 Const     P   :  PChar     =   ' T h i s|_|i s|_|a|_|PCHAR |_|s t r i n.g' ;
                           S   :  Char    =   ' s '  ;


                 b e g i n
                    W r i t e l n ( 'P  , |_|s t a r t i n|g_|from|_|f i r s|t_|''s' ' |_|: |_|',StrScan   ( P , s ) ) ;
                    W r i t e l n ( 'P  , |_|s t a r t i n|g_|from|_|l a s t|_|''s'' |_|: |_|',StrRScan    ( P , s ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 366

                 _________________________________________________________________________19.1.___FUNCTIONS_AND_PROCEDURES.________*
 *____________________
                 19.1.22         StrUpper

Declaration:      Function  StrUpper  (P  :  PChar)  :    PChar;

Description:      Converts P to an all-uppercase string.  Returns P.

       Errors:    None.

     See also:    Upcase () , StrLower (363)


                 For an example, see StrLower (363)
                                                                                 367


Chapter   20


The   SYSUTILS   unit.



This chapter describes the sysutils unit.  The sysutils unit was largely written by Gertjan
Schouten, and completed by michael Van Canneyt.  It aims to be compatible to the Delphi
sysutils unit, but in contrast with the latter, it is designed to work on multiple platforms.  It
is implemented on all supported platforms.

This chapter starts out with a definition of all types and constants that are defined, followed
by an overview of functions grouped by functionality, and lastly the complete explanation of
each function.
20.1          Constants  and  types


The following general-purpose constants are defined:


const
    SecsPerDay  =  24  *  60  *  60;  //  Seconds  and  milliseconds  per  day
    MSecsPerDay  =  SecsPerDay  *  1000;
    DateDelta  =  693594;             //  Days  between  1/1/0001  and  12/31/1899
    Eoln  =  #10;


The following types are used frequently in date and time functions.  They are the same on
all platforms.


type
    TSystemTime  =  record
         Year,  Month,  Day:  word;
         Hour,  Minute,  Second,  MilliSecond:  word;
    end  ;


    TDateTime  =  double;


    TTimeStamp  =  record
         Time:  integer;     {  Number  of  milliseconds  since  midnight  }
         Date:  integer;     {  One  plus  number  of  days  since  1/1/0001  }
    end  ;


The following type is used in the FindFirst (403),FindNext (404) and FindClose (403) functions.
The  win32  version  differs  from  the  other  versions.   If  code  is  to  be  portable,  that  part
shouldn't be used.



                                                            368

_____________________________________________________________________________________20.1.___CONSTANTS_AND_TYPES___________________*
 *___
Type
   THandle  =  Longint;
   TSearchRec  =  Record
      Time,Size,  Attr  :  Longint;
      Name  :  TFileName;
      ExcludeAttr  :  Longint;
      FindHandle  :  THandle;
      {$ifdef  Win32}
      FindData  :  TWin32FindData;
      {$endif}
      end;


The following constants are file-attributes that need to be matched in the findfirst call.


Const
   faReadOnly    =  $00000001;
   faHidden       =  $00000002;
   faSysFile     =  $00000004;
   faVolumeId    =  $00000008;
   faDirectory  =  $00000010;
   faArchive     =  $00000020;
   faAnyFile     =  $0000003f;


The following constants can be used in the FileOpen (400) call.


Const
   fmOpenRead            =  $0000;
   fmOpenWrite          =  $0001;
   fmOpenReadWrite    =  $0002;


The following constants can be used in the FileSeek (401) call.


Const
   fsFromBeginning  =  0;
   fsFromCurrent     =  1;
   fsFromEnd            =  2;
The following variables are used in the case translation routines.


type
    TCaseTranslationTable  =  array[0..255]  of  char;
var
    UpperCaseTable:  TCaseTranslationTable;
    LowerCaseTable:  TCaseTranslationTable;


The initialization code of the sysutils unit fills these tables with the appropriate values.  For
the win32 and go32v2 versions, this information is obtained from the operating system.

The following constants control the formatting of dates.  For the Win32 version of the sysutils
unit,  these  constants  are  set  according  to  the  internationalization  settings  of  Windows  by
the initialization code of the unit.


Const
    DateSeparator:  char  =  '-';



                                                                369

_____________________________________________________________________________________20.1.___CONSTANTS_AND_TYPES___________________*
 *___
    ShortDateFormat:  string  =  'd/m/y';
    LongDateFormat:  string  =  'dd"  "mmmm"  "yyyy';
    ShortMonthNames:  array[1..12]  of  string[128]  =
        ('Jan','Feb','Mar','Apr','May','Jun',
         'Jul','Aug','Sep','Oct','Nov','Dec');
    LongMonthNames:  array[1..12]  of  string[128]  =
        ('January','February','March','April',
         'May','June','July','August',
         'September','October','November','December');
    ShortDayNames:  array[1..7]  of  string[128]  =
        ('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
    LongDayNames:  array[1..7]  of  string[128]  =
        ('Sunday','Monday','Tuesday','Wednesday',
           'Thursday','Friday','Saturday');


The following constants control the formatting of times.  For the Win32 version of the sysutils
unit,  these  constants  are  set  according  to  the  internationalization  settings  of  Windows  by
the initialization code of the unit.


Const
    ShortTimeFormat:  string  =  'hh:nn';
    LongTimeFormat:  string  =  'hh:nn:ss';
    TimeSeparator:  char  =  ':';
    TimeAMString:  string[7]  =  'AM';
    TimePMString:  string[7]  =  'PM';


The following constants control the formatting of currencies and numbers.  For the Win32
version  of  the  sysutils  unit,  these  constants  are  set  according  to  the  internationalization
settings of Windows by the initialization code of the unit.


Const
   DecimalSeparator  :  Char  =  '.';
   ThousandSeparator  :  Char  =  ',';
   CurrencyDecimals  :  Byte  =  2;
   CurrencyString  :  String[7]  =  '$';
   {  Format  to  use  when  formatting  currency  :
      0  =  $1             1  =  1$               2  =  $  1          3  =  1  $
      4  =  Currency  string  replaces  decimal  indicator.
             e.g.  1$50
    }
   CurrencyFormat  :  Byte  =  1;
   {  Same  as  above,  only  for  negative  currencies:
      0  =  ($1)
      1  =  -$1
      2  =  $-1
      3  =  $1-
      4  =  (1$)
      5  =  -1$
      6  =  1-$
      7  =  1$-
      8  =  -1  $
      9  =  -$  1
      10  =  $  1-
    }
   NegCurrFormat  :  Byte  =  5;



                                                                370

__________________________________________________________________________20.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
The following types are used in various string functions.


type
    PString  =  ^String;
    TFloatFormat  =  (ffGeneral,  ffExponent,  ffFixed,  ffNumber,  ffCurrency);


The following constants are used in the file name handling routines.  Do not use a slash of
backslash character directly as a path separator; instead use the OsDirSeparator character.


Const
   DirSeparators  :  set  of  char  =  ['/','\'];
{$ifdef  Linux}
   OSDirSeparator  =  '/';
{$else}
   OsDirSeparator  =  '\';
{$endif}
20.2          Function  list  by  category


What follows is a listing of the available functions, grouped by category.  For each function
there is a reference to the page where you can find the function.
20.2.1        String  functions

Functions for handling strings.


Name_______________________________________________Description_________________________________________________Page___________

  AnsiCompareStr                   Compare two strings                                                         409

  AnsiCompareText                  Compare two strings, case insensitive                                  410

  AnsiExtractQuotedStr             Removes quotes from string                                               411

  AnsiLastChar                     Get last character of string                                                411

  AnsiLowerCase                    Convert string to all-lowercase                                            412

  AnsiQuotedStr                    Qoutes a string                                                                412

  AnsiStrComp                      Compare strings case-sensitive                                            413

  AnsiStrIComp                     Compare strings case-insensitive                                         413

  AnsiStrLComp                     Compare L characters of strings case sensitive                      415

  AnsiStrLIComp                    Compare L characters of strings case insensitive                    416

  AnsiStrLastChar                  Get last character of string                                                414

  AnsiStrLower                     Convert string to all-lowercase                                            416

  AnsiStrUpper                     Convert string to all-uppercase                                           417

  AnsiUpperCase                    Convert string to all-uppercase                                           418

  AppendStr                        Append 2 strings                                                              418

  AssignStr                        Assign value of strings on heap                                           419

  CompareStr                       Compare two strings case sensitive                                      420

  CompareText                      Compare two strings case insensitive                                   421
                                                                371

__________________________________________________________________________20.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
  DisposeStr                       Remove string from heap                                                   422

  IsValidIdent                     Is string a valid pascal identifier                                         432

  LeftStr                          Get first N characters of a string                                        433

  LoadStr                          Load string from resources                                                 433

  LowerCase                        Convert string to all-lowercase                                            433

  NewStr                           Allocate new string on heap                                               434

  RightStr                         Get last N characters of a string                                         435

  StrAlloc                         Allocate memory for string                                                407

  StrBufSize                       Reserve memory for a string                                               407

  StrDispose                       Remove string from heap                                                   408

  StrPas                           Convert PChar to pascal string                                          408

  StrPCopy                         Copy pascal string                                                            408

  StrPLCopy                        Copy N bytes of pascal string                                             408

  UpperCase                        Convert string to all-uppercase                                           439
20.2.2        Formatting  strings

Functions for formatting strings.


Name_______________________________________________Description_________________________________________________Page___________

  AdjustLineBreaks                 Convert line breaks to line breaks for system                        409

  FormatBuf                        Format a buffer                                                                431

  Format                           Format arguments in string                                                425

  FmtStr                           Format buffer                                                                   425

  QuotedStr                        Quote a string                                                                  434

  StrFmt                           Format arguments in a string                                             435

  StrLFmt                          Format maximum L characters in a string                            435

  TrimLeft                         Remove whitespace at the left of a string                             438

  TrimRight                        Remove whitespace at the right of a string                           438

  Trim                             Remove whitespace at both ends of a string                         437
20.2.3        File  input/output  routines

Functions for reading/writing to file.


Name_______________________________________________Description_________________________________________________Page___________

  FileCreate                       Create a file and return handle                                           397

  FileOpen                         Open file end return handle                                               400

  FileRead                         Read from file                                                                  401

  FileSeek                         Set file position                                                                401

  FileTruncate                     Truncate file length                                                           403

  FileWrite                        Write to file                                                                     403

  FileClose                        Close file handle                                                               397



                                                                372

__________________________________________________________________________20.2.___FUNCTION_LIST_BY_CATEGORY________________________*
 *___
20.2.4        File  handling  routines

Functions for file manipulation.


Name_______________________________________________Description_________________________________________________Page___________

  AddDisk                          Add sisk to list of disk drives                                             389

  ChangeFileExt                    Change extension of file name                                            392

  CreateDir                        Create a directory                                                            389

  DeleteFile                       Delete a file                                                                     392

  DiskFree                         Free space on disk                                                            390

  DiskSize                         Total size of disk                                                              390

  ExpandFileName                   Create full file name                                                          393

  ExpandUNCFileName                Create full UNC file name                                                 394

  ExtractFileDir                   Extract directory part of filename                                       394

  ExtractFileDrive                 Extract drive part of filename                                            395

  ExtractFileExt                   Extract extension part of filename                                      395

  ExtractFileName                  Extract name part of filename                                            395

  ExtractFilePath                  Extrct path part of filename                                               396

  ExtractRelativePath              Construct relative path between two files                             396

  FileAge                          Return file age                                                                 396

  FileDateToDateTime               Convert file date to system date                                         382

  FileExists                       Determine whether a file exists on disk                                398

  FileGetAttr                      Get attributes of file                                                         398

  FileGetDate                      Get date of last file modification                                         400

  FileSearch                       Search for file in path                                                        401

  FileSetAttr                      Get file attributes                                                             402

  FileSetDate                      Get file dates                                                                   402

  FindFirst                        Start finding a file                                                            403

  FindNext                         Find next file                                                                   404

  GetCurrentDir                    Return current working directory                                        391

  RemoveDir                        Remove a directory from disk                                             391

  RenameFile                       Rename a file on disk                                                        405

  SetCurrentDir                    Set current working directory                                             391

  SetDirSeparators                 Set directory separator characters                                       406

  FindClose                        Stop searching a file                                                          403

  DoDirSeparators                  Replace directory separator characters                                 393
20.2.5        Date/time  routines

Functions for date and time handling.


Name_______________________________________________Description_________________________________________________Page___________

                                                                373

________________________________________________________20.3.___MISCELLANEOUS_CONVERSION_ROUTINES__________________________________*
 *___
  DateTimeToFileDate               Convert DateTime type to file date                                     376

  DateTimeToStr                    Construct string representation of DateTime                        377

  DateTimeToString                 Construct string representation of DateTime                        377

  DateTimeToSystemTime               Convert DateTime to system time                                     378

  DateTimeToTimeStamp               Convert DateTime to timestamp                                        378

  DateToStr                        Construct string representation of date                                379

  Date                             Get current date                                                               376

  DayOfWeek                        Get day of week                                                               379

  DecodeDate                       Decode DateTime to year month and day                            380

  DecodeTime                       Decode DateTime to hours, minutes and seconds                  380

  EncodeDate                       Encode year, day and month to DateTime                           381

  EncodeTime                       Encode hours, minutes and seconds to DateTime                  381

  FormatDateTime                   Return string representation of DateTime                            382

  IncMonth                         Add 1 to month                                                               383

  IsLeapYear                       Determine if year is leap year                                             383

  MSecsToTimeStamp                 Convert nr of milliseconds to timestamp                              384

  Now                              Get current date and time                                                 384

  StrToDateTime                    Convert string to DateTime                                               385

  StrToDate                        Convert string to date                                                       385

  StrToTime                        Convert string to time                                                       386

  SystemTimeToDateTime               Convert system time to datetime                                       387

  TimeStampToDateTime               Convert time stamp to DateTime                                       387

  TimeStampToMSecs                 Convert Timestamp to number of millicseconds                    388

  TimeToStr                        return string representation of Time                                    388

  Time                             Get current tyme                                                              387
20.3          Miscellaneous  conversion  routines


Functions for various conversions.


Name_______________________________________________Description_________________________________________________Page___________

  BCDToInt                         Convert BCD number to integer                                         419

  CompareMem                       Compare two memory regions                                            420

  FloatToStrF                      Convert float to formatted string                                        423

  FloatToStr                       Convert float to string                                                       422

  FloatToText                      Convert float to string                                                       424

  GetDirs                          Split string in list of directories                                          404

  IntToHex                         return hexadecimal representation of integer                         431

  IntToStr                         return decumal representation of integer                              432

  StrToIntDef                      Convert string to integer with default value                          437

  StrToInt                         Convert string to integer                                                   436



                                                                374

______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS______________________*
 *___
20.4          Date  and  time  functions



20.4.1        Date  and  time  formatting  characters

Various date and time formatting routines accept a format string.  to format the date and
or time.  The following characters can be used to control the date and time formatting:


c  :  shortdateformat + ' ' + shorttimeformat

d  :  day of month

dd   :  day of month (leading zero)

ddd    :  day of week (abbreviation)

dddd     :  day of week (full)

ddddd      :  shortdateformat

dddddd       :  longdateformat

m   :  month

mm     :  month (leading zero)

mmm       :  month (abbreviation)

mmmm         :  month (full)

y  :  year (four digits)

yy   :  year (two digits)

yyyy     :  year (with century)

h  :  hour

hh   :  hour (leading zero)

n  :  minute

nn   :  minute (leading zero)

s  :  second

ss  :  second (leading zero)

t  :  shorttimeformat

tt  :  longtimeformat

am/pm        :  use 12 hour clock and display am and pm accordingly

a/p    :  use 12 hour clock and display a and p accordingly

/  :  insert date seperator

: :  insert time seperator

"xx"     :  literal text

'xx'   :  literal text

                                                                375

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 20.4.2        TDateTime

Declaration:      TDateTime  =  Double;

Description:      Many  functions  return  or  require  a  TDateTime  type,  which  contains  a  date  and  time  in
                 encoded form.  The date and time are converted to a double as follows:
                 20.4.3        Date

Declaration:      Function  Date:    TDateTime;

Description:      Date  returns  the  current  date  in  TDateTime  format.   For  more  information  about  the
                 TDateTime type, see TDateTime (376).

       Errors:    None.

     See also:    Time (387),Now (384), TDateTime (376).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example1      ;


                 {  T h i s  program       d e m o n s t r a t e st h e Date     f u n c t i o n}


                 u s e s  s y s u t i l;s


                 Var   YY  ,MM   ,DD   :   Word   ;


                 Begin
                   W r i t e l n( ' Date   |_|: |_|',Date  ) ;
                  DeCodeDate         ( Date   , YY  ,MM  ,DD  ) ;
                   W r i t e l n( format      ( ' Date   |_|i s|_|(DD/MM  / YY ): |_|%d /%  d/%  d |_|', [dd ,mm  , yy  ] ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.4        DateTimeToFileDate

Declaration:      Function  DateTimeToFileDate(DateTime  :    TDateTime)  :    Longint;

Description:      DateTimeToFileDate function converts a date/time indication in TDateTime format to a
                 filedate function, such as returned for instance by the FileAge (396) function.

       Errors:    None.

     See also:    Time  (387),  Date  (376),  FileDateToDateTime  (382),  DateTimeToSystemTime  (378),  Date-
                 TimeToTimeStamp (378)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example2      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  D a t e T i m e T o F i l e D a tfeu n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( ' F i l e T i m e|_|o|f_|now|_|would  |_|be : |_|',DateTimeToFileDate              ( Now   ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 376

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 20.4.5        DateTimeToStr

Declaration:      Function  DateTimeToStr(DateTime:    TDateTime):    string;

Description:      DateTimeToStr returns a string representation of  DateTime using the formatting specified
                 in ShortDateTimeFormat.  It corresponds to a call to FormatDateTime('c',DateTime) (see
                 section 20.4.1, page 375).

       Errors:    None.

     See also:    FormatDateTime (382), TDateTime (376).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example3      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  DateTimeToStr           f u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( ' Today   |_|i s|_|: |_|',DateTimeToStr        (Now   ) ) ;
                    W r i t e l n ( ' Today   |_|i s|_|: |_|',FormatDateTime         ( 'c ' ,Now   ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.6        DateTimeToString

Declaration:      Procedure  DateTimeToString(var  Result:    string;  const  FormatStr:    string;  const
                 DateTime:    TDateTime);

Description:      DateTimeToString  returns  in  Result  a  string  representation  of  DateTime  using  the  for-
                 matting specified in FormatStr.

                 for  a  list  of  characters  that  can  be  used  in  the  FormatStr  formatting  string,  see  section
                 20.4.1, page 375.

       Errors:    In case a wrong formatting character is found, an EConvertError is raised.

     See also:    FormatDateTime (382), section 20.4.1, page 375.


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example4      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  D a t e T i m e T o S t r i nfgu n c t i o n}


                 Uses     s y s u t i l;s



                 Procedure        t o d a y ( Fmt    :   s t r i n g) ;


                 Var    S  :   A n s i S t r i n;g


                 b e g i n
                    DateTimeToString              (S , Fmt  , Date   ) ;
                    W r i t e l n ( S ) ;
                 end  ;


                 Procedure        Now    ( Fmt    :   s t r i n g) ;


                 Var    S  :   A n s i S t r i n;g



                                                                                 377

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________


                 b e g i n
                    DateTimeToString              (S , Fmt  , Time   ) ;
                    W r i t e l n ( S ) ;
                 end  ;


                 Begin
                    Today     (  ' "Today    |_|i s|_|"dddd |_|dd |_|mmmm |_|y' ) ;
                    Today     (  ' "Today    |_|i s|_|"d|_|mmm|_|yy' ) ;
                    Today     (  ' "Today    |_|i s|_|"d/mmm  / yy ' ) ;
                    Now    ( ' ' 'The   |_|t i m|e_|i s|_|''am/ pmh  : n :s ' ) ;
                    Now    ( ' ' 'The   |_|t i m|e_|i s|_|''hh: nn : ssam   /pm  ' ) ;
                    Now    ( ' ' 'The   |_|t i m|e_|i s|_|''t t') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.7        DateTimeToSystemTime

Declaration:      Procedure  DateTimeToSystemTime(DateTime:    TDateTime;  var  SystemTime:    TSystemTime);

Description:      DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime format to
                 a system time SystemTime.

       Errors:    None.

     See also:    DateTimeToFileDate (376), SystemTimeToDateTime (387), DateTimeToTimeStamp (378)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example5      ;


                 {  T h i s  program       d e m o n s t r a t e st h e DateTimeToSystemTime                 f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   ST    :  TSystemTime         ;


                 Begin
                    DateTimeToSystemTime               (Now   , ST ) ;
                    With     St   do
                        b e g i n
                        W r i t e l n( ' Today    |_|i s|_||_||_||_|',y e,a'r/ ',month    , ' / ', Day  ) ;
                        W r i t e l n( ' The  |_|t i m e|_|i s|_|',Hour  , ' : ',m i n u t e, ' : ',Second     , ' . ', M i l l i S*
 * e c o n)d;
                        end  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.8        DateTimeToTimeStamp

Declaration:      Function  DateTimeToTimeStamp(DateTime:    TDateTime):    TTimeStamp;

Description:      DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime format to
                 a TTimeStamp format.

       Errors:    None.

     See also:    DateTimeToFileDate (376), SystemTimeToDateTime (387), DateTimeToSystemTime (378)
                                                                                 378

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example6      ;


                 {  T h i s  program       d e m o n s t r a t e st h e DateTimeToTimeStamp                 f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   TS    :  TTimeStamp        ;


                 Begin
                    TS  := DateTimeToTimeStamp                (Now   ) ;
                    With     TS   do
                        b e g i n
                        W r i t e l n( ' Now  |_|i s|_|',time   , ' |_|m i l l i s e c o|n_d|p a s|t_|m i d n i g'h)t;
                        W r i t e l n( ' Today    |_|i s|_|', Date   , ' |_|d a y|s_|p a s|t_|1 / 1 / 0 0 0 1)';
                        end  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.9        DateToStr

Declaration:      Function  DateToStr(Date:    TDateTime):    string;

Description:      DateToStr converts Date to a string representation.  It uses ShortDateFormat as it's for-
                 matting string.  It is hence completely equivalent to a FormatDateTime('ddddd',  Date).

       Errors:    None.

     See also:    TimeToStr (388), DateTimeToStr (377), FormatDateTime (382), StrToDate (385)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example7      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  D a t e T o S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n(Format      ( ' Today    |_|i s: |_|%s', [DateToStr       (Date    ) ] ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.10         DayOfWeek

Declaration:      Function  DayOfWeek(DateTime:    TDateTime):    integer;

Description:      DayOfWeek  returns  the  day  of  the  week  from  DateTime.   Sunday  is  counted  as  day  1,
                 Saturday  is  counted  as  day  7.   The  result  of  DayOfWeek  can  serve  as  an  index  to  the
                 LongDayNames constant array, to retrieve the name of the day.

       Errors:    None.

     See also:    Date (376), DateToStr (379)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example8      ;


                 {  T h i s  program       d e m o n s t r a t e st h e DayOfWeek         f u n c t i o n}
                                                                                 379

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( ' Today   ' ' s |_|day |_|i s|_|',LongDayNames        [DayOfWeek       ( Date   ) ] ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.11         DecodeDate

Declaration:      Procedure  DecodeDate(Date:    TDateTime;  var  Year,  Month,  Day:    word);

Description:      DecodeDate  decodes  the  Year,  Month  and  Day  stored  in  Date,  and  returns  them  in  the
                 Year, Month and Day variables.

       Errors:    None.

     See also:    EncodeDate (381), DecodeTime (380).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example9      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  DecodeDate         f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   YY  ,MM   ,DD   :   Word   ;


                 Begin
                    DecodeDate        (Date   , YY  ,MM  ,DD  ) ;
                    W r i t e l n ( Format      ( ' Today   |_|i s|_|%d/% d /% d ' , [dd  ,mm  , yy  ] ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.12         DecodeTime

Declaration:      Procedure  DecodeTime(Time:    TDateTime;  var  Hour,  Minute,  Second,  MilliSecond:
                 word);

Description:      DecodeDate decodes the hours, minutes, second and milliseconds stored in Time, and returns
                 them in the Hour, Minute and Second and MilliSecond variables.

       Errors:    None.

     See also:    EncodeTime (381), DecodeDate (380).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example10      ;


                 {  T h i s  program       d e m o n s t r a t e st h e DecodeTime          f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   HH  ,MM   ,SS  ,MS  :  Word   ;


                 Begin
                    DecodeTime        (Time   , HH  ,MM  ,SS  ,MS  ) ;
                    W r i t e l n ( format    ( ' The  |_|t i m e|_|i|s_|%d:% d:%  d .% d ' , [hh  ,mm  , s s, ms  ] ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 380

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 20.4.13         EncodeDate

Declaration:      Function  EncodeDate(Year,  Month,  Day  :word):    TDateTime;

Description:      EncodeDate encodes the Year, Month and Day variables to a date in TDateTime format.  It
                 does the opposite of the DecodeDate (380) procedure.

                 The parameters must lie withing valid ranges (boundaries included):

                 Year   must be between 1 and 9999.

                 Month     must be within the range 1-12.

                 Day   msut be between 1 and 31.

       Errors:    In case one of the parameters is out of it's valid range, 0 is returned.

     See also:    EncodeTime (381), DecodeDate (380).

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example11      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  EncodeDate         f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   YY  ,MM   ,DD   :   Word   ;


                 Begin
                    DecodeDate         ( Date   , YY ,MM   ,DD  ) ;
                    WriteLn       ( ' Today   |_|i s|_|: |_|',FormatDateTime          ( ' dd  |_|mmmm |_|y y y y',EnCodeDate       *
 * (YY  ,Mm  , Dd  ) ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.14         EncodeTime

Declaration:      Function  EncodeTime(Hour,  Minute,  Second,  MilliSecond:word):    TDateTime;

Description:      EncodeTime  encodes  the  Hour,  Minute,  Second,  MilliSecond  variables  to  a  TDateTime
                 format result.  It does the opposite of the DecodeTime (380) procedure.

                 The parameters must have a valid range (boundaries included):

                 Hour    must be between 0 and 23.

                 Minute,second         must both be between 0 and 59.

                 Millisecond      must be between 0 and 999.

       Errors:    In case one of the parameters is outside of it's valid range, 0 is returned.

     See also:    EncodeDate (381), DecodeTime (380).

                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example12      ;


                 {  T h i s  program       d e m o n s t r a t e st h e EncodeTime          f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   Hh  ,MM   ,SS  ,MS    :  Word   ;


                 Begin
                    DeCodeTime         ( Time   , Hh ,MM   ,SS  ,MS  ) ;
                    W r i t e l n ( ' P r e s e n t|_|Time |_|i s|_|: |_|',FormatDateTime        ( 'hh  :mm  : s s' , EnCodeTime   *
 *      (HH  ,MM   ,SS  ,MS  ) ) @
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 381

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 20.4.15         FileDateToDateTime

Declaration:      Function  FileDateToDateTime(Filedate  :    Longint)  :    TDateTime;

Description:      FileDateToDateTime converts the date/time encoded in filedate to a TDateTime encoded
                 form.  It can be used to convert date/time values returned by the FileAge (396) or FindFirst
                 (403)/FindNext (404) functions to TDateTime form.

       Errors:    None.

     See also:    DateTimeToFileDate (376)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example13      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e D a t e T o D a t e T i mfeu n c t i o n}


                 Uses     s y s u t i l;s


                 Var
                    ThisAge       :   L o n g i n t;


                 Begin
                  Write      ( 'ex13   . pp  |_|c r e a t e|d_|on|_|:)';
                   ThisAge     := F i l e A g e(' ex13   .pp  ' ) ;
                   W r i t e l n( DateTimeToStr          ( FileDateToDateTime             ( ThisAge     ) ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.16         FormatDateTime

Declaration:      Function  FormatDateTime(FormatStr:    string;  DateTime:    TDateTime):string;

Description:      FormatDateTime formats the date and time encoded in DateTime according to the format-
                 ting given in FormatStr.  The complete list of formatting characters can be found in section
                 20.4.1, page 375.

       Errors:    On error (such as an invalid character in the formatting string), and EConvertError excep-
                 tion is raised.

     See also:    DateTimeToStr (377), DateToStr (379), TimeToStr (388), StrToDateTime (385)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example14      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  FormatDateTime            f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    ThisMoment         :  TDateTime       ;


                 Begin
                    ThisMoment        := Now  ;
                    W r i t e l n ( 'Now   |_|: |_|',FormatDateTime         ( 'hh  :mm  ' , ThisMoment       ) ) ;
                    W r i t e l n ( 'Now   |_|: |_|',FormatDateTime         ( 'DD  |_|MM|_|YYYY  ' ,ThisMoment        ) ) ;
                    W r i t e l n ( 'Now   |_|: |_|',FormatDateTime         ( 'c ' , ThisMoment       ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 382

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 20.4.17         IncMonth

Declaration:      Function  IncMonth(const  DateTime:    TDateTime;  NumberOfMonths:    integer):    TDateTime;

Description:      IncMonth increases the month number in DateTime with NumberOfMonths.  It wraps the re-
                 sult as to get a month between 1 and 12, and updates the year accordingly.  NumberOfMonths
                 can be negative, and can be larger than 12 (in absolute value).

       Errors:    None.

     See also:    Date (376), Time (387), Now (384)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example15      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  IncMonth       f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    ThisDay       :  TDateTime       ;


                 Begin
                    ThisDay     :=  Date   ;
                    W r i t e l n ( ' ThisDay     |_|: |_|',DateToStr     ( ThisDay     ) ) ;
                    W r i t e l n ( ' 6 |_|months   |_|ago |_|: ',DateToStr      ( IncMonth      ( ThisDay     , - 6 ) ) ) ;
                    W r i t e l n ( ' 6 |_|months   |_|from |_|now  |_|: ', DateToStr       (IncMonth      ( ThisDay      , 6 ) ) )*
 * ;
                    W r i t e l n ( ' 1 2 |_|months  |_|ago  |_|: ',DateToStr      ( IncMonth      (ThisDay      , - 1 2 ) ) ) ;
                    W r i t e l n ( ' 1 2 |_|months  |_|from  |_|now |_|: ' , DateToStr      ( IncMonth      ( ThisDay     , 1 2 ) *
 *) ) ;
                    W r i t e l n ( ' 1 8 |_|months  |_|ago  |_|: ',DateToStr      ( IncMonth      (ThisDay      , - 1 8 ) ) ) ;
                    W r i t e l n ( ' 1 8 |_|months  |_|from  |_|now |_|: ' , DateToStr      ( IncMonth      ( ThisDay     , 1 8 ) *
 *) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.18         IsLeapYear

Declaration:      Function  IsLeapYear(Year:    Word):    boolean;

Description:      IsLeapYear returns True if  Year is a leap year, False otherwise.

       Errors:    None.

     See also:    IncMonth (383), Date (376)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example16      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  I s L e a p Y e a rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   YY  ,MM   ,dd   :   Word   ;


                 Procedure        T e s t Y e a r (Y   :  Word    ) ;


                 b e g i n
                    W r i t e l n ( Y , ' |_|i|s_|l e a|p_|y e a|r_|: |_|',I s L e a p Y e(aYr) ) ;
                 end  ;


                 Begin
                    DeCodeDate        (Date   , YY  ,mm  ,dd  ) ;



                                                                                 383

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                    T e s t Y e a r(yy  ) ;
                    T e s t Y e a r( 2 0 0 0 ) ;
                    T e s t Y e a r( 1 9 0 0 ) ;
                    T e s t Y e a r( 1 6 0 0 ) ;
                    T e s t Y e a r( 1 9 9 2 ) ;
                    T e s t Y e a r( 1 9 9 5 ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.19         MSecsToTimeStamp

Declaration:      Function  MSecsToTimeStamp(MSecs:    Comp):    TTimeStamp;

Description:      MSecsTiTimeStamp converts the given number of milliseconds to a TTimeStamp date/time
                 notation.

                 Use TTimeStamp variables if you need to keep very precise track of time.

       Errors:    None.

     See also:    TimeStampToMSecs (388), DateTimeToTimeStamp (378),


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example17      ;


                 {  T h i s  program       d e m o n s t r a t e st h e MSecsToTimeStamp              f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   MS    :  Comp   ;
                       TS    :  TTimeStamp        ;
                       DT    :  TDateTime       ;
                 Begin
                    TS  := DateTimeToTimeStamp              ( Now  ) ;
                    W r i t e l n ( 'Now   |_|i n|_|d a y|s_|s i n c|e_|1 / 1 / 0 0 0 1 |_||_||_||_||_||_|:,|_|'TS.Date) ;
                    W r i t e l n ( 'Now   |_|i n|_|m i l l i s e c|s_|s i n|c_e|m i d n i g|h_t|: |_|',TS.Time  ) ;
                    MS  := TimeStampToMSecs            ( TS ) ;
                    W r i t e l n ( 'Now   |_|i n|_|m i l l i s e c|s_|s i n|c_e|1 / 1 / 0 0 0 1 |_|:,|_|'MS) ;
                    MS  := MS  -1000*3600*2;
                    TS  := MSecsToTimeStamp            (MS  ) ;
                    DT  := TimeStampToDateTime              ( TS  ) ;
                    W r i t e l n ( 'Now   |_|minus   |_|1 |_|day|_|: |_|',DateTimeToStr       ( DT  ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.20         Now

Declaration:      Function  Now:    TDateTime;

Description:      Now returns the current date and time.  It is equivalent to Date+Time.

       Errors:    None.

     See also:    Date (376), Time (387)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example18      ;


                 {  T h i s  program       d e m o n s t r a t e st h e Now     f u n c t i o n}
                                                                                 384

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( 'Now   |_|: |_|',DateTimeToStr        ( Now  ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.21         StrToDate

Declaration:      Function  StrToDate(const  S:  string):    TDateTime;

Description:      StrToDate converts the string S to a TDateTime date value.  The Date must consist of 1 to
                 three digits, separated by the DateSeparator character.  If two numbers are given, they are
                 supposed to form the day and month of the current year.  If only one number is given, it is
                 supposed to represent the day of the current month.  (This is not supported in Delphi)

                 The  order  of  the  digits  (y/m/d,  m/d/y,  d/m/y)  is  determined  from  the  ShortDateFormat
                 variable.

       Errors:    On error (e.g.  an invalid date or invalid character), an EConvertError exception is raised.

     See also:    StrToTime (386), DateToStr (379)n TimeToStr (388).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example19      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  S t r T o D a t ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t S t r ( S  :   S t r i n g) ;


                 b e g i n
                    W r i t e l n ( S , ' |_|: |_|',DateToStr     (StrToDate       ( S ) ) ) ;
                 end  ;


                 Begin


                    W r i t e l n ( ' S h o r t D a t e F o r m a|t_|',S h o r t D a t e F o r m)a;t
                    T e s t S t r(DateTimeToStr          (Date    ) ) ;
                    T e s t S t r(' 0 5 / 0 5 / 1 9 9 9)';
                    T e s t S t r(' 5 / 5 ') ;
                    T e s t S t r(' 5 ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.22         StrToDateTime

Declaration:      Function  StrToDateTime(const  S:  string):    TDateTime;

Description:      StrToDateTime converts the string S to a TDateTime date and time value.  The Date must
                 consist of 1 to three digits, separated by the DateSeparator character.  If two numbers are
                 given, they are supposed to form the day and month of the current year.  If only one number
                 is given, it is supposed to represent the day of the current month.  (This is not supported in
                 Delphi)

                 The  order  of  the  digits  (y/m/d,  m/d/y,  d/m/y)  is  determined  from  the  ShortDateFormat
                 variable.

       Errors:    On error (e.g.  an invalid date or invalid character), an EConvertError exception is raised.



                                                                                 385

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
     See also:    StrToDate (385), StrToTime (386), DateTimeToStr (377)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example20      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  StrToDateTime           f u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t S t r ( S  :   S t r i n g) ;


                 b e g i n
                    W r i t e l n ( S , ' |_|: |_|',DateTimeToStr        (StrToDateTime          (S  ) ) ) ;
                 end  ;


                 Begin


                    W r i t e l n ( ' S h o r t D a t e F o r m a|t_|',S h o r t D a t e F o r m)a;t
                    T e s t S t r(DateTimeToStr          (Now   ) ) ;
                    T e s t S t r(' 0 5 - 0 5 - 1 9 9 9 |_|1 5 : 5)0;'
                    T e s t S t r(' 5 - 5 |_|1 3 : 3 0)';
                    T e s t S t r(' 5 |_|1 : 3P0M ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.23         StrToTime

Declaration:      Function  StrToTime(const  S:  string):    TDateTime;

Description:      StrToTime converts the string  S to a TDateTime time value.  The time must consist of 1
                 to 4 digits, separated by the TimeSeparator character.  If two numbers are given, they are
                 supposed to form the hour and minutes.

       Errors:    On error (e.g.  an invalid date or invalid character), an EConvertError exception is raised.

     See also:    StrToDate (385), StrToDateTime (385), TimeToStr (388)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example21      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  StrToTime        f u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t S t r ( S  :   S t r i n g) ;


                 b e g i n
                    W r i t e l n ( S , ' |_|: |_|',TimeToStr     (StrToTime       ( S ) ) ) ;
                 end  ;


                 Begin
                     t e s t s t r( TimeToStr       (Time    ) ) ;
                     t e s t s t r( ' 1 2 : 0 0 ') ;
                     t e s t s t r( ' 1 5 : 3 0 ') ;
                     t e s t s t r( ' 3 : 3 0PM ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 386

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
                 20.4.24         SystemTimeToDateTime

Declaration:      Function  SystemTimeToDateTime(const  SystemTime:    TSystemTime):    TDateTime;

Description:      SystemTimeToDateTime  converts  a  TSystemTime  record  to  a  TDateTime  style  date/time
                 indication.

       Errors:    None.

     See also:    DateTimeToSystemTime (378)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example22      ;


                 {  T h i s  program       d e m o n s t r a t e st h e SystemTimeToDateTime                 f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   ST    :  TSystemTime         ;


                 Begin
                    DateTimeToSystemTime               (Now   , ST ) ;
                    With     St   do
                        b e g i n
                        W r i t e l n( ' Today    |_|i s|_||_||_||_|',y e,a'r/ ',month    , ' / ', Day  ) ;
                        W r i t e l n( ' The  |_|t i m e|_|i s|_|',Hour  , ' : ',m i n u t e, ' : ',Second     , ' . ', M i l l i S*
 * e c o n)d;
                        end  ;
                    W r i t e l n ( ' C o n v e r t e d|_|: |_|',DateTimeToStr       (SystemTimeToDateTime               ( ST  ) ) *
 *) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.25         Time

Declaration:      Function  Time:    TDateTime;

Description:      Time returns the current time in TDateTime format.  The date part of the TDateTimeValue
                 is set to zero.

       Errors:    None.

     See also:    Now (384), Date (376)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example23      ;


                 {  T h i s  program       d e m o n s t r a t e st h e Time     f u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( ' The  |_|t i m e|_|i|s_|: |_|',TimeToStr    ( Time   ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.26         TimeStampToDateTime

Declaration:      Function  TimeStampToDateTime(const  TimeStamp:    TTimeStamp):    TDateTime;

Description:      TimeStampToDateTime converts TimeStamp to a TDateTime format variable.  It is the inverse
                 operation of  DateTimeToTimeStamp (378).



                                                                                 387

                 ______________________________________________________________________________20.4.___DATE_AND_TIME_FUNCTIONS_____*
 *____________________
       Errors:    None.

     See also:    DateTimeToTimeStamp (378), TimeStampToMSecs (388)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example24      ;


                 {  T h i s  program       d e m o n s t r a t e st h e TimeStampToDateTime                 f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   TS    :  TTimeStamp        ;
                       DT    :  TDateTime       ;


                 Begin
                    TS  := DateTimeToTimeStamp                (Now   ) ;
                    With     TS   do
                        b e g i n
                        W r i t e l n( ' Now  |_|i s|_|',time   , ' |_|m i l l i s e c o|n_d|p a s|t_|m i d n i g'h)t;
                        W r i t e l n( ' Today    |_|i s|_|', Date   , ' |_|d a y|s_|p a s|t_|1 / 1 / 0 0 0 1)';
                        end  ;
                    DT  := TimeStampToDateTime              ( TS  ) ;
                    W r i t e l n ( ' T o g e t h e r|_|t h i|s_|i|s_|: |_|',DateTimeToStr       (DT  ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.4.27         TimeStampToMSecs

Declaration:      Function  TimeStampToMSecs(const  TimeStamp:    TTimeStamp):    comp;

Description:      TimeStampToMSecs converts TimeStamp to the number of seconds since 1/1/0001.

                 Use TTimeStamp variables if you need to keep very precise track of time.

       Errors:    None.

     See also:    MSecsToTimeStamp (384), TimeStampToDateTime (387)


                 For an example, see MSecsToTimeStamp (384).
                 20.4.28         TimeToStr

Declaration:      Function  TimeToStr(Time:    TDateTime):    string;

Description:      TimeToStr  converts  the  time  in  Time  to  a  string.   It  uses  the  ShortTimeFormat  vari-
                 able  to  see  what  formatting  needs  to  be  applied.   It  is  therefor  entirely  equivalent  to  a
                 FormatDateTime('t',Time) call.

       Errors:    None.

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example25      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  TimeToStr        f u n c t i o n}


                 Uses     s y s u t i l;s
                                                                                 388

                 ________________________________________________________________________________________________20.5.___DISK_FUNCT*
 *IONS________________
                 Begin
                    W r i t e l n ( ' The  |_|c u r r e n|t_|t i m|e_|i|s_|: |_|',TimeToStr    ( Time   ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.5          Disk  functions



                 20.5.1        AddDisk  (Linux  only)

Declaration:      Function  AddDisk  (Const  PAth  :    String)  :    Longint;

Description:      On  Linux  both  the  DiskFree  (42)  and  DiskSize  (42)  functions  need  a  file  on  the  specified
                 drive, since is required for the statfs system call.

                 These filenames are set in drivestr[0..26], and the first 4 have been preset to :

                 Disk 0    '.'  default drive - hence current directory is used.

                 Disk 1    '/fd0/.'  floppy drive 1.

                 Disk 2    '/fd1/.'  floppy drive 2.

                 Disk 3    '/' C: equivalent of DOS is the root partition.

                 Drives 4..26 can be set by your own applications with the AddDisk call.

                 The AddDisk call adds Path to the names of drive files, and returns the number of the disk
                 that corresponds to this drive.  If you add more than 21 drives, the count is wrapped to 4.

       Errors:    None.

     See also:    DiskFree (390), DiskSize (390)
                 20.5.2        CreateDir

Declaration:      Function  CreateDir(Const  NewDir  :    String)  :    Boolean;

Description:      CreateDir creates a new directory with name NewDir.  If the directory doesn't contain an
                 absolute path, then the directory is created below the current working directory.

                 The function returns True if the directory was successfully created, False otherwise.

       Errors:    In case of an error, the function returns False.

     See also:    RemoveDir (391)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example26      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  C r e a t e D i rand    RemoveDir         f u n c t i o n *
 *s}
                 {  Run    t h i s  program       t w i c e i n   t h e same     d i r e c t o r y}


                 Uses     s y s u t i l;s


                 Begin
                    I f  Not     F i l e E x i s t(s'NewDir     ' )  then
                        I f  Not    C r e a t e D i r( ' NewDir    ' )  Then
                           W r i t e l n ( ' F a i l e d|_|to|_|c r e a t|e_|d i r e c t o|r_y|!)'
                        e l s e
                           W r i t e l n ( ' C r e a t e d|_|"NewDir   " |_|d i r e c t o r'y)
                    E l s e



                                                                                 389

                 ________________________________________________________________________________________________20.5.___DISK_FUNCT*
 *IONS________________
                        I f  Not    RemoveDir        ( ' NewDir    ' )  Then
                           W r i t e l n ( ' F a i l e d|_|to|_|remove   |_|d i r e c t o r|y_|!)'
                        e l s e
                           W r i t e l n ( ' Removed     |_|"NewDir    " |_|d i r e c t o r'y) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.5.3        DiskFree

Declaration:      Function  DiskFree(Drive  :    Byte)  :    Longint;

Description:      DiskFree returns the free space (in bytes) on disk Drive.  Drive is the number of the disk
                 drive:

                 0for the current drive.

                 1for the first floppy drive.

                 2for the second floppy drive.

                 3for the first hard-disk parttion.

                 4-26  for all other drives and partitions.

                 Remark  Under  linux,  and  Unix  in  general,  the  concept  of  disk  is  different  than  the  dos
                 one, since the filesystem is seen as one big directory tree.  For this reason, the DiskFree and
                 DiskSize (42) functions must be mimicked using filenames that reside on the partitions.  For
                 more information, see AddDisk (389)

       Errors:    On error, -1 is returned.

     See also:    DiskSize (390), AddDisk (389)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example27      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  D i s k F r e ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    Write     (  'S i z e|_|o f|_|c u r r e n|t_|d i s|k_||_||_||_||_||_||_|:,|_|'D i s(k0S)i)z;e
                    W r i t e l n ( ' |_|( = |_|',D i s k S i z(e0 ) d i v  1 0 2 4 ,'k ) ' ) ;
                    Write     (  'F r e e|_|s p a c e|_|o|f_|c u r r e n|t_|d i s|k_|: |_|',D i s k f r(e0e) ) ;
                    W r i t e l n ( ' |_|( = |_|',D i s k f r e(e0 ) d i v  1 0 2 4 ,'k ) ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.5.4        DiskSize

Declaration:      Function  DiskSize(Drive  :    Byte)  :    Longint;

Description:      DiskSize returns the size (in bytes) of disk Drive.  Drive is the number of the disk drive:

                 0for the current drive.

                 1for the first floppy drive.

                 2for the second floppy drive.

                 3for the first hard-disk parttion.

                 4-26  for all other drives and partitions.
                                                                                 390

                 ________________________________________________________________________________________________20.5.___DISK_FUNCT*
 *IONS________________
                 Remark  Under  linux,  and  Unix  in  general,  the  concept  of  disk  is  different  than  the  dos
                 one, since the filesystem is seen as one big directory tree.  For this reason, the DiskFree (42)
                 and DiskSize functions must be mimicked using filenames that reside on the partitions.  For
                 more information, see AddDisk (389)

       Errors:    On error, -1 is returned.

     See also:    DiskFree (390), AddDisk (389)


                 For an example, see DiskFree (390).
                 20.5.5        GetCurrentDir

Declaration:      Function  GetCurrentDir  :    String;

Description:      GetCurrentDir returns the current working directory.

       Errors:    None.

     See also:    SetCurrentDir (391), DiskFree (42), DiskSize (42)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example28      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  G e t C u r r e n t D i rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( ' C u r r e n t|_|D i r e c t o|r_y|i|s_|: |_|',G e t C u r r e n t D)i;r
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.5.6        RemoveDir

Declaration:      Function  RemoveDir(Const  Dir  :    String)  :    Boolean;

Description:      RemoveDir  removes  directory  Dir  from  the  disk.   If  the  directory  is  not  absolue,  it  is
                 appended to the current working directory.

       Errors:    In case of error (e.g.  the directory isn't empty) the function returns False.  If successful,
                 True is returned.

     See also:


                 For an example, see CreateDir (389).
                 20.5.7        SetCurrentDir

Declaration:      Function  SetCurrentDir(Const  NewDir  :    String)  :    Boolean;

Description:      SetCurrentDir sets the current working directory of your program to NewDir.  It returns
                 True if the function was successfull, False otherwise.

       Errors:    In case of error, False is returned.

     See also:    GetCurrentDir (391)



                                                                                 391

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example29      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  S e t C u r r e n t D i rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    I f   S e t C u r r e n t D i r(' . . ')  Then
                        W r i t e l n( ' Now  |_|i n|_|d i r e c t o r|y_|',G e t C u r r e n t D)i r
                    e l s e
                        W r i t e l n( ' Change     |_|d i r e c t o r|y_|to|_|. .f|_|a i l e.d') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6          File  handling  functions



                 20.6.1        ChangeFileExt

Declaration:      Function  ChangeFileExt(const  FileName,  Extension:    string):    string;

Description:      ChangeFileExt  changes  the  file  extension  in  FileName  to  Extension.    The  extension
                 Extension includes the starting .  (dot).  The previous extension of  FileName are all char-
                 acters after the last ., the .  character included.

                 If  FileName doesn't have an extension, Extension is just appended.

       Errors:    None.

     See also:    ExtractFileName (395), ExtractFilePath (396), ExpandFileName (393)
                 20.6.2        DeleteFile

Declaration:      Function  DeleteFile(Const  FileName  :    String)  :    Boolean;

Description:      DeleteFile  deletes  file  FileName  from  disk.   The  function  returns  True  if  the  file  was
                 successfully removed, False otherwise.

       Errors:    On error, False is returned.

     See also:    FileCreate (397), FileExists (398)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example31      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  D e l e t e F i l ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Var
                    L i n e  :   S t r i n g;
                    F , I  :   L o n g i n t;


                 Begin
                    F :=  F i l e C r e a t(e' t e s t.t x t' ) ;
                    L i n e:=  'Some    |_|s t r i n|g_|l i n.e'#10;
                    For    I :=1    to   1 0  do
                        F i l e W r i t e( F ,L i n e [ 1 ] ,Length    ( L i n e) ) ;



                                                                                 392

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                    F i l e C l o s e(F ) ;
                    D e l e t e F i l e('t e s t. t x t' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.3        DoDirSeparators

Declaration:      Procedure  DoDirSeparators(Var  FileName  :    String);

Description:      This function replaces all directory separators ''and  '/' to the directory separator character
                 for the current system.

       Errors:    None.

     See also:    ExtractFileName (395), ExtractFilePath (396)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example32      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  D o D i r S e p a r a t o r sf u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( F   :  S t r i n g) ;


                 b e g i n
                    W r i t e l n ( ' B e f o r e|_|: |_|',F) ;
                    D o D i r S e p a r a t o r s(F ) ;
                    W r i t e l n ( ' A f t e r|_||_|: |_|',F) ;
                 end  ;


                 Begin
                    T e s t i t ( G e t C u r r e n t D i)r;
                    T e s t i t ( ' c : \pp  \b i n\ win32    ' ) ;
                    T e s t i t ( ' / u s r/ l i b/ f p c' ) ;
                    T e s t i t ( ' \ u s r\ l i b\ f p c' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.4        ExpandFileName

Declaration:      Function  ExpandFileName(Const  FileName  :    string):    String;

Description:      ExpandFileName  expands  the  filename  to  an  absolute  filename.   It  changes  all  directory
                 separator characters to the one appropriate for the system first.

       Errors:    None.

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395), ExtractRelativePath (396)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example33      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  E x p a n d F i l e N a m ef u n c t i o n}


                 Uses     s y s u t i l;s
                                                                                 393

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 Procedure        T e s t i t ( F   :  S t r i n g) ;


                 b e g i n
                    W r i t e l n ( F , ' |_|e x p a n d|s_|to|_|: |_|',ExpandFileName       ( F ) ) ;
                 end  ;


                 Begin
                    T e s t i t( 'ex33   . pp ' ) ;
                    T e s t i t(ParamStr       ( 0 ) ) ;
                    T e s t i t( ' /pp / b i n/ win32    / ppc386    ' ) ;
                    T e s t i t( ' \pp \ b i n\ win32    \ ppc386    ' ) ;
                    T e s t i t( ' . ') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.5        ExpandUNCFileName

Declaration:      Function  ExpandUNCFileName(Const  FileName  :    string):    String;

Description:      ExpandUNCFileName runs ExpandFileName (393) on FileName and then attempts to replace
                 the driveletter by the name of a shared disk.

       Errors:

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395), ExtractRelativePath (396)
                 20.6.6        ExtractFileDir

Declaration:      Function  ExtractFileDir(Const  FileName  :    string):    string;

Description:      ExtractFileDir returns only the directory part of  FileName, not including a driveletter.
                 The  directory  name  has  NO  ending  directory  separator,  in  difference  with  ExtractFilePath
                 (396).

       Errors:    None.

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395), ExtractRelativePath (396)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example34      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  E x t r a c t F i l e N a m ef u n c t i o n}
                 {$H  +}
                 Uses     s y s u t i l;s


                 Procedure        T e s t i t(F   :  S t r i n g) ;


                 b e g i n
                   W r i t e l n( ' F i l e N a m e|_||_||_||_||_||_|:,|_|'F) ;
                   W r i t e l n( ' Has  |_|Name  |_||_||_||_||_||_|:,|_|'E x t r a c t F i l(eFN)a)m;e
                   W r i t e l n( ' Has  |_|Path  |_||_||_||_||_||_|:,|_|'E x t r a c t F i l(eFP)a)t;h
                   W r i t e l n( ' Has  |_|E x t e n s i o|n_|: |_|',E x t r a c t F i l e E(xFt) ) ;
                   W r i t e l n( ' Has  |_|D i r e c t o r|y_|: |_|',E x t r a c t F i l e D(iFr) ) ;
                   W r i t e l n( ' Has  |_|D r i v e|_||_||_||_||_|:,|_|'E x t r a c t F i l e(DFr)i)v;e
                 end  ;

                                                                                 394

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 Begin
                    T e s t i t ( Paramstr      ( 0 ) ) ;
                    T e s t i t ( ' / u s r/ l o c a l/b i n/ m y s q l d') ;
                    T e s t i t ( ' c : \pp  \b i n\ win32    \ ppc386    . e x e' ) ;
                    T e s t i t ( ' / pp / b i n/ win32   / ppc386     . e x e' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.7        ExtractFileDrive

Declaration:      Function  ExtractFileDrive(const  FileName:    string):    string;

Description:      Extract

       Errors:

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395), ExtractRelativePath (396)


                 For an example, see ExtractFileDir (394).
                 20.6.8        ExtractFileExt

Declaration:      Function  ExtractFileExt(const  FileName:    string):    string;

Description:      ExtractFileExt returns the extension (including the .(dot) character) of  FileName.

       Errors:    None.

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395), ExtractRelativePath (396)


                 For an example, see ExtractFileDir (394).
                 20.6.9        ExtractFileName

Declaration:      Function  ExtractFileName(const  FileName:    string):    string;

Description:      ExtractFileName  returns  the  filename  part  from  FileName.  The  filename  consists  of  all
                 characters after the last directory separator character ('/' or '') or drive letter.

                 The full filename can always be reconstucted by concatenating the result of  ExtractFilePath
                 (396) and ExtractFileName.

       Errors:    None.

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395),ExtractRelativePath (396)


                 For an example, see ExtractFileDir (394).



                                                                                 395

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 20.6.10         ExtractFilePath

Declaration:      Function  ExtractFilePath(const  FileName:    string):    string;

Description:      ExtractFilePath returns the path part (including driveletter) from FileName.  The path
                 consists of all characters before the last directory separator character ('/' or ''), including the
                 directory separator itself.  In case there is only a drive letter, that will be returned.

                 The full filename can always be reconstucted by concatenating the result of ExtractFilePath
                 and ExtractFileName (395).

       Errors:    None.

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395), ExtractRelativePath (396)


                 For an example, see ExtractFileDir (394).
                 20.6.11         ExtractRelativePath

Declaration:      Function  ExtractRelativePath(Const  BaseName,DestNAme  :    String):    String;

Description:      ExtractRelativePath  constructs  a  relative  path  to  go  from  BaseName  to  DestName.   If
                 DestName is on another drive (Not on Linux) then the whole Destname is returned.

                 Note:  This function does not exist in the Delphi unit.

       Errors:    None.

     See also:    ExtractFileName  (395),  ExtractFilePath  (396),  ExtractFileDir  (394),  ExtractFileDrive  (395),
                 ExtractFileExt (395),


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example35      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  E x t r a c t R e l a t i v e P a tfhu n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( FromDir     , ToDir      :  S t r i n g) ;


                 b e g i n
                    Write     (  'From   |_|" ',FromDir     , ' " |_|to|_|" ',ToDir    ,' " |_|v i a|_|")';
                    W r i t e l n ( E x t r a c t R e l a t i v e P a(tFhromDir    , ToDir    ) ,' " ') ;
                 end  ;


                 Begin
                   T e s t i t(  ' /pp / s r c/ c o m p i l e r', ' /pp / b i n/ win32    / ppc386    ' ) ;
                   T e s t i t(  ' /pp / b i n/ win32    / ppc386    ' , ' /pp / s r c/ c o m p i l e r') ;
                   T e s t i t(  'e : /pp  / b i n/ win32   / ppc386     ', ' d : /pp / s r c/ c o m p i l e r') ;
                   T e s t i t(  'e : \pp  \ b i n\ win32   \ ppc386     ', ' d : \pp \ s r c\ c o m p i l e r') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.12         FileAge

Declaration:      Function  FileAge(Const  FileName  :    String):    Longint;

Description:      FileAge returns the last modification time of file FileName.  The FileDate format can be
                 transformed to TDateTime format with the FileDateToDateTime (382) function.



                                                                                 396

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
       Errors:    In case of errors, -1 is returned.

     See also:    FileDateToDateTime (382), FileExists (398), FileGetAttr (398)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example36      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e A g e f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   TDateTime      ;
                        f a  :   L o n g i n t;
                 Begin
                    f a := F i l e A g e(' ex36   . pp ' ) ;
                    I f  Fa  <>-1     then
                        b e g i n
                        S:=  FileDateTodateTime             ( f a ) ;
                        W r i t e l n( ' I ' 'm |_|from  |_|',DateTimeToStr          (S ) )
                        end  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.13         FileClose

Declaration:      Procedure  FileClose(Handle  :    Longint);

Description:      FileClose closes the file handle Handle.  After this call, attempting to read or write from
                 the handle will result in an error.

       Errors:    None.

     See also:    FileCreate (397), FileWrite (403), FileOpen (400), FileRead (401), FileTruncate (403), FileSeek
                 (401)


                 For an example, see FileCreate (397)
                 20.6.14         FileCreate

Declaration:      Function  FileCreate(Const  FileName  :    String)  :    Longint;

Description:      FileCreate creates a new file with name FileName on the disk and returns a file handle
                 which can be used to read or write from the file with the FileRead (401) and FileWrite (403)
                 functions.

                 If a file with name FileName already existed on the disk, it is overwritten.

       Errors:    If an error occurs (e.g.  disk full or non-existent path), the function returns -1.

     See also:    FileClose (397), FileWrite (403), FileOpen (400), FileRead (401), FileTruncate (403), FileSeek
                 (401)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example37      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e C r e a t ef u n c t i o n}


                 Uses     s y s u t i l;s



                                                                                 397

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________


                 Var    I ,J ,F   :   L o n g i n t;


                 Begin
                    F :=  F i l e C r e a t e(' t e s t. d a t' ) ;
                    I f  F =-1    then
                        Halt   ( 1 ) ;
                    For    I :=0    to   1 0 0  do
                        F i l e W r i t(eF , I, S i z e O f(i ) ) ;
                    F i l e C l o s e(f ) ;
                    F := FileOpen        ( ' t e s t.d a t ', fmOpenRead        ) ;
                    For    I :=0    to   1 0 0  do
                        b e g i n
                        F i l e R e a d( F , J, SizeOF     (J ) ) ;
                        I f  J<>  I   then
                           W r i t e l n ( ' Mismatch      |_|a t|_|f i l|e_|p o s i t i o|n_|',I)
                        end  ;
                    F i l e S e e k(F , 0 ,f s F r o m B e g i n n i n)g;
                    Randomize       ;
                    Repeat
                        F i l e S e e k(F, Random    ( 1 0 0 ) * 4 ,f s F r o m B e g i n n i n)g;
                        F i l e R e a d( F , J, S i z e O f(J ) ) ;
                        W r i t e l n( ' Random     |_|r e a d|_|: |_|',j) ;
                    U n t i l  J>80;
                    F i l e C l o s e(F ) ;
                    F := FileOpen      ( ' t e s t. d a t' ,fmOpenWrite         ) ;
                    I :=50*    S i z e O f(L o n g i n t) ;
                    I f   F i l e T r u n c a t(eF, I)   then
                        W r i t e l n(' S u c c e s s F u l l|y_|t r u n c a t|e_d|f i l|e_|to|_|',I,' |_|b y t e.s') ;
                    F i l e C l o s e(F ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.15         FileExists

Declaration:      Function  FileExists(Const  FileName  :    String)  :    Boolean;

Description:      FileExists returns True if a file with name FileName exists on the disk, False otherwise.

       Errors:    None.

     See also:    FileAge (396), FileGetAttr (398), FileSetAttr (402)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example38      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e E x i s t sf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    I f   F i l e E x i s t(sParamStr      ( 0 ) ) Then
                        W r i t e l n( ' A l l|_|i s|_|w e l,l|_|I|_|seem |_|to |_|e x i s.t' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.16         FileGetAttr

Declaration:      Function  FileGetAttr(Const  FileName  :    String)  :    Longint;



                                                                                 398

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
Description:      FileGetAttr  returns  the  attribute  settings  of  file  FileName.   The  attribute  is  a  OR-ed
                 combination of the following constants:

                 faReadOnly        The file is read-only.

                 faHidden      The file is hidden.  (On linux, this means that the filename starts with a dot)

                 faSysFile     The file is a system file (On linux, this means that the file is a character, block
                       or FIFO file).

                 faVolumeId        Volume Label.  Not possible under linux.

                 faDirectory       File is a directory.

                 faArchive      file is an archive.  Not possible on linux.

       Errors:    In case of error, -1 is returned.

     See also:    FileSetAttr (402), FileAge (396), FileGetDate (400).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example40      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e G e t A t t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( Name     :  S t r i n g) ;


                 Var    F  :   L o n g i n t;


                 Begin
                    F :=  F i l e G e t A t t(rName   ) ;
                    I f  F <>-1     then
                        b e g i n
                        W r i t e l n( ' T e s t i n g|_|: |_|',Name ) ;
                        I f  (F   and    f a R e a d O n l)y<>0    then
                           W r i t e l n ( ' F i l e|_|i s|_|ReadOnly    ') ;
                        I f  (F   and    f a H i d d e n)<>0    then
                           W r i t e l n ( ' F i l e|_|i s|_|h i d d e'n) ;
                        I f  (F   and    f a S y s F i l e)<>0    then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|s y s t e|m_|f i'l)e;
                        I f  (F   and    f a V o l u m e I)D<>0    then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|d i s|k_|l a b e'l) ;
                        I f  (F   and    f a A r c h i v e)<>0    then
                           W r i t e l n ( ' F i l e|_|i s|_|a r t c h i v|e_|f i'l)e;
                        I f  (F   and    f a D i r e c t o r)y<>0    then
                           W r i t e l n ( ' F i l e|_|i s|_|a|_|d i r e c t o'r)y;
                        end
                    e l s e
                      W r i t e l n ( ' E r r o r|_|r e a d i n|g_|a t t r i b i t|e_s|o|f_|',Name ) ;
                 end  ;


                 b e g i n
                     t e s t i t( ' ex40   . pp ' ) ;
                     t e s t i t( ParamStr      ( 0 ) ) ;
                     t e s t i t(  ' . ') ;
                     t e s t i t( ' / ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 399

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 20.6.17         FileGetDate

Declaration:      Function  FileGetDate(Handle  :    Longint)  :    Longint;

Description:      FileGetdate returns the filetime of the opened file with filehandle Handle.  It is the same as
                 FileAge (396), with this difference that FileAge only needs the file name, while FilegetDate
                 needs an open file handle.

       Errors:    On error, -1 is returned.

     See also:    FileAge (396)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example39      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e G e t D a t ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    F ,D   :  L o n g i n t;


                 Begin
                    F :=  F i l e C r e a t(e' t e s t.d a t' ) ;
                    D :=  F i l e G e t D a t(eD) ;
                    W r i t e l n ( ' F i l e|_|c r e r a t e|d_|on|_|',DateTimeToStr        ( FileDateToDateTime              (D )*
 * ) ) ;
                    F i l e C l o s e(F ) ;
                    D e l e t e F i l e('t e s t. d a t' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.18         FileOpen

Declaration:      Function  FileOpen(Const  FileName  :    string;  Mode  :    Integer)  :    Longint;

Description:      FileOpen  opens  a  file  with  name  FileName  with  mode  Mode.   Mode  can  be  one  of  the
                 following constants:

                 fmOpenRead          The file is opened for reading.

                 fmOpenWrite          The file is opened for writing.

                 fmOpenReadWrite              The file is opened for reading and writing.

                 If the file has been successfully opened, it can be read from or written to (depending on the
                 Mode parameter) with the FileRead (401) and FileWrite functions.

                 Remark that you cannot open a file if it doesn't exist yet, i.e.  it will not be created for you.
                 If you want tp create a new file, or overwrite an old one, use the FileCreate (397) function.

       Errors:    On Error, -1 is returned.

     See also:    FileClose (397), FileWrite (403), FileCreate (397), FileRead (401), FileTruncate (403), FileSeek
                 (401)


                 For an example, see FileRead (401)

                                                                                 400

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 20.6.19         FileRead

Declaration:      Function  FileRead(Handle  :    Longint;  Var  Buffer;  Count  :    longint)  :    Longint;

Description:      FileRead reads Count bytes from file-handle Handle and stores them into Buffer.  Buffer
                 must be at least Count bytes long.  No checking on this is performed, so be careful not to
                 overwrite any memory.  Handle must be the result of a FileOpen (400) call.

       Errors:    On error, -1 is returned.

     See also:    FileClose (397), FileWrite (403), FileCreate (397), FileOpen (400), FileTruncate (403), FileSeek
                 (401)


                 For an example, see FileOpen (400)
                 20.6.20         FileSearch

Declaration:      Function  FileSearch(Const  Name,  DirList  :    String)  :    String;

Description:      FileSearch looks for the file Name in DirList, where dirlist is a list of directories, separated
                 by semicolons or colons.  It returns the full filename of the first match found.

       Errors:    On error, an empty string is returned.

     See also:    ExpandFileName (393), FindFirst (403)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example41      ;


                 {  Program       to    d e m o n s t r a t et h e F i l e S e a r c h f u n c t i o n.  }


                 Uses     S y s u t i l;s


                 Const
                 { $ i f d e f l i n u x}
                    FN   =   ' f i n d';
                    P  =    ' . : /b i n: /u s r/ b i n' ;
                 { $ e l s e}
                    FN   =   ' f i n d.e x e ';
                    P  =   ' c : \dos  ; c : \windows      ;c : \ windows     \ s y s t e m;c : \windows     \ s y s t e m 3 2';
                 { $ e n d i f}


                 b e g i n
                    W r i t e l n ( ' f i n d|_|i s|_|i n|_|: |_|',F i l e S e a r c(hFN, P ) ) ;
                _end__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.21         FileSeek

Declaration:      Function  FileSeek(Handle,Offset,Origin  :    Longint)  :    Longint;

Description:      FileSeek sets the file pointer on position Offset, starting from Origin.  Origin can be one
                 of the following values:

                 fsFromBeginning           Offset is relative to the first byte of the file.  This position is zero-based.
                       i.e.  the first byte is at offset 0.

                 fsFromCurrent          Offset is relative to the current position.

                                                                                 401

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 fsFromEnd        Offset is relative to the end of the file.  This means that Offset can only be
                       zero or negative in this case.

                 If successfull, the function returns the new file position, relative to the beginning of the file.

                 Remark:  The abovementioned constants do not exist in Delphi.

       Errors:    On error, -1 is returned.

     See also:    FileClose (397), FileWrite (403), FileCreate (397), FileOpen (400) FileRead (401), FileTruncate
                 (403)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example42      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i l e S e t A t t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    I f   F i l e S e t A t t r(' ex40   .pp  ' , f a R e a d O n l yor   f a H i d d e n)=0   then
                        W r i t e l n( ' S u c c e s s f u l l|y_|made |_|f i l e|_|h i d d e|n_|and|_|r e a-do n l y. ')
                    e l s e
                        W r i t e l n( ' Coulnd     '' t |_|make  |_|f i l|e_|h i d d e|n_|and|_|r e a-do n l y. ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________

                 For an example, see FileCreate (397)
                 20.6.22         FileSetAttr  (Not  on  Linux)

Declaration:      Function  FileSetAttr(Const  Filename  :    String;  Attr:    longint)  :    Longint;

Description:      FileSetAttr sets the attributes of  FileName to Attr.  If the function was successful, 0 is
                 returned, -1 otherwise.

                 Attr can be set to an OR-ed combination of the pre-defined faXXX constants.

       Errors:    On error, -1 is returned (always on linux).

     See also:    FileGetAttr (398), FileGetDate (400), FileSetDate (402).
                 20.6.23         FileSetDate  (Not  on  Linux)

Declaration:      Function  FileSetDate(Handle,Age  :    Longint)  :    Longint;

Description:      FileSetDate sets the file date of the file with handle Handle to Age, where Age is a DOS
                 date-and-time stamp value.

                 The function returns zero of successfull.

       Errors:    On Linux, -1 is always returned, since this is impossible to implement.  On Windows and
                 DOS, a negative error code is returned.

     See also:
                                                                                 402

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                 20.6.24         FileTruncate

Declaration:      Function  FileTruncate(Handle,Size:    Longint)  :    boolean;

Description:      FileTruncate  truncates  the  file  with  handle  Handle  to  Size  bytes.   The  file  must  have
                 been  opened  for  writing  prior  to  this  call.  The  function  returns  True  is  successful,  False
                 otherwise.

       Errors:    On error, the function returns False.

     See also:    FileClose  (397),  FileWrite  (403),  FileCreate  (397),  FileOpen  (400)  FileRead  (401),  FileSeek
                 (401)


                 For an example, see FileCreate (397).
                 20.6.25         FileWrite

Declaration:      Function  FileWrite(Handle  :    Longint;  Var  Buffer;  Count  :    Longint)  :    Longint;

Description:      FileWrite writes Count bytes from Buffer to the file with handle Handle.  Prior to this
                 call, the file must have been opened for writing.  Buffer must be at least Count bytes large,
                 or a memory access error may occur.

                 The function returns the number of bytes written, or -1 in case of an error.

       Errors:    In case of error, -1 is returned.

     See also:    FileClose (397), FileCreate (397), FileOpen (400) FileRead (401), FileTruncate (403), FileSeek
                 (401)


                 For an example, see FileCreate (397).
                 20.6.26         FindClose

Declaration:      Procedure  FindClose(Var  F  :  TSearchrec);

Description:      FindClose ends a series of FindFirst (403)/FindNext (404) calls, and frees any memory used
                 by these calls.  It is absolutely necessary to do this call, or huge memory losses may occur.

       Errors:    None.

     See also:    FindFirst (403), FindNext (404).


                 For an example, see FindFirst (403).
                 20.6.27         FindFirst

Declaration:      Function  FindFirst(Const  Path  :    String;  Attr  :    Longint;  Var  Rslt  :    TSearchRec)
                 :    Longint;

Description:      FindFirst looks for files that match the name (possibly with wildcards) in Path and at-
                 tributes Attr.  It then fills up the Rslt record with data gathered about the file.  It returns
                 0 if a file matching the specified criteria is found, a nonzero value (-1 on linux) otherwise.

                 The  Rslt  record  can  be  fed  to  subsequent  calls  to  FindNext,  in  order  to  find  other  files
                 matching the specifications.

                 remark:  A FindFirst call must always be followed by a FindClose (403) call with the same
                 Rslt record.  Failure to do so will result in memory loss.



                                                                                 403

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
       Errors:    On error the function returns -1 on linux, a nonzero error code on Windows.

     See also:    FindClose (45)FindCloseSys, FindNext (404).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example43      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F i n d F i r s tf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    I n f o :   TSearchRec       ;
                        Count     :   L o n g i n t;


                 Begin
                    Count    : = 0 ;
                    I f   F i n d F i r s t( ' * .pp ' , f a A n y F i l e,I n f o)=0   then
                        b e g i n
                        Repeat
                           I n c( Count    ) ;
                           With     I n f o  do
                               W r i t e l n( Name    : 4 0 ,S i z e: 1 5 ) ;
                        U n t i l FindNext      ( i n f o)<>0;
                        end  ;
                    F i n d C l o s e(I n f o) ;
                    W r i t e l n ( ' F i n i s h e d|_|s e a r c.h|_|Found |_|',Count    , ' |_|m a t c h e's) ;


                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.28         FindNext

Declaration:      Function  FindNext(Var  Rslt  :    TSearchRec)  :    Longint;

Description:      FindNext finds a next occurrence of a search sequence initiated by FindFirst.  If another
                 record matching the criteria in Rslt is found, 0 is returned, a nonzero constant is returned
                 otherwise.

                 remark:  The last FindNext call must always be followed by a FindClose call with the same
                 Rslt record.  Failure to do so will result in memory loss.

       Errors:    On error (no more file is found), a nonzero constant is returned.

     See also:    FindFirst (403), FindClose (45)


                 For an example, see FindFirst (403)
                 20.6.29         GetDirs

Declaration:      Function  GetDirs(Var  DirName  :    String;  Var  Dirs  :    Array  of  pchar)  :    Longint;

Description:      GetDirs splits DirName in a null-byte separated list of directory names, Dirs is an array of
                 PChars, pointing to these directory names.  The function returns the number of directories
                 found, or -1 if none were found.  DirName must contain only OSDirSeparator as Directory
                 separator chars.

       Errors:    None.

     See also:    ExtractRelativePath (396)



                                                                                 404

                 ______________________________________________________________________________20.6.___FILE_HANDLING_FUNCTIONS_____*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example45      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  G e t D i r s f u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Var    D i r s :   Array    [ 0 . . 1 2 7 ]of    p c h a r;
                        I ,Count      :  l o n g i n t;
                        D i r, NewDir      :  S t r i n g;


                 Begin
                    D i r:=  G e t C u r r e n t D i;r
                    W r i t e l n ( ' D i r|_|: |_|',D i r) ;
                    NewDir     := ' ' ;
                    c o u n t:=  G e t D i r s(D i r,D i r s) ;
                    For    I :=0    to   Count     do
                        b e g i n
                        NewDir    :=  NewDir    + ' / '+ StrPas    ( D i r s[ I ] ) ;
                        W r i t e l n( NewDir     ) ;
                        end  ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.6.30         RenameFile

Declaration:      Function  RenameFile(Const  OldName,  NewName  :    String)  :    Boolean;

Description:      RenameFile renames a file from OldName to NewName.  The function returns True if success-
                 ful, False otherwise.

                 Remark:  you cannot rename across disks or partitions.

       Errors:    On Error, False is returned.

     See also:    DeleteFile (392)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example44      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  R e n a m e F i l ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    F  :   L o n g i n t;
                        S  :   S t r i n g;


                 Begin
                    S :=  'Some   |_|s h o r t|_|f i l.e';
                    F :=  F i l e C r e a t e(' t e s t. dap  ' ) ;
                    F i l e W r i t e(F, S [ 1 ] ,Length    ( S ) ) ;
                    F i l e C l o s e(F ) ;
                    I f  RenameFile         ( ' t e s t. dap  ' , 't e s t. d a t' )  then
                        W r i t e l n( ' S u c c e s s f u l l|y_|renamed   |_|f i l e s. ') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 405

                 _____________________________________________________________________________________________20.7.___PCHAR_FUNCTIO*
 *NS__________________
                 20.6.31         SetDirSeparators

Declaration:      Function  SetDirSeparators(Const  FileName  :    String)  :    String;

Description:      SetDirSeparators returns FileName with all possible DirSeparators replaced by OSDirSeparator.

       Errors:    None.

     See also:    ExpandFileName (393), ExtractFilePath (396), ExtractFileDir (394)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example47      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  S e t D i r S e p a r a t o rfsu n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( S e t D i r S e p a r a t o r(s' /pp\ b i n/ win32    \ ppc386    ' ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.7          PChar  functions



                 20.7.1        Introduction

                 Most PChar functions are the same as their counterparts in the STRINGS unit.  The following
                 functions are the same :


                    1.  StrCat (357) :  Concatenates two PChar strings.

                    2.  StrComp (358) :  Compares two PChar strings.

                    3.  StrCopy (358) :  Copies a PChar string.

                    4.  StrECopy (359) :  Copies a PChar string and returns a pointer to the terminating null
                        byte.

                    5.  StrEnd (360) :  Returns a pointer to the terminating null byte.

                    6.  StrIComp (360) :  Case insensitive compare of 2 PChar strings.

                    7.  StrLCat (361) :  Appends at most L characters from one PChar to another PChar.

                    8.  StrLComp (361) :  Case sensitive compare of at most L characters of 2 PChar strings.

                    9.  StrLCopy (362) :  Copies at most L characters from one PChar to another.

                   10.  StrLen (362) :  Returns the length (exclusive terminating null byte) of a PChar string.

                   11.  StrLIComp (363) :  Case insensitive compare of at most L characters of 2 PChar strings.

                   12.  StrLower (363) :  Converts a PChar to all lowercase letters.

                   13.  StrMove (363) :  Moves one PChar to another.

                   14.  StrNew  (364)  :  Makes  a  copy  of  a  PChar  on  the  heap,  and  returns  a  pointer  to  this
                        copy.

                   15.  StrPos (365) :  Returns the position of one PChar string in another?
                                                                                 406

                 _____________________________________________________________________________________________20.7.___PCHAR_FUNCTIO*
 *NS__________________
                   16.  StrRScan (366) :  returns a pointer to the last occurrence of on PChar string in another
                        one.

                   17.  StrScan (366) :  returns a pointer to the first occurrence of on PChar string in another
                        one.

                   18.  StrUpper (367) :  Converts a PChar to all uppercase letters.


                 The  subsequent  functions  are  different  from  their  counterparts  in  STRINGS,  although  the
                 same examples can be used.
                 20.7.2        StrAlloc

Declaration:      Function  StrAlloc(Size:    cardinal):    PChar;

Description:      StrAlloc  reserves  memory  on  the  heap  for  a  string  with  length  Len,  terminating  #0  in-
                 cluded, and returns a pointer to it.

                 Additionally,  StrAlloc  allocates  4  extra  bytes  to  store  the  size  of  the  allocated  memory.
                 Therefore this function is NOT compatible with the StrAlloc (357) function of the Strings
                 unit.

       Errors:    None.

     See also:    StrBufSize (407), StrDispose (408), StrAlloc (357)


                 For an example, see StrBufSize (407).
                 20.7.3        StrBufSize

Declaration:      Function  StrBufSize(var  Str:    PChar):    cardinal;

Description:      StrBufSize returns the memory allocated for Str.  This function ONLY gives the correct
                 result if  Str was allocated using StrAlloc (407).

       Errors:    If no more memory is available, a runtime error occurs.

     See also:    StrAlloc (407).StrDispose (408).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example46      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  S t r B u f S i z ef u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Const     S    =   'Some    |_|n i c|e_|s t r i n'g;


                 Var   P   :   Pchar   ;


                 Begin
                      P := S t r A l l o c(Length    ( S ) + 1 ) ;
                      StrPCopy      (P , S ) ;
                      Write     ( P ,   ' |_|has|_|l e n g t h|_|',l e n g t(hS ) ) ;
                      W r i t e l n ( ' |_|and |_||_|b u f f|e_r|s i z|e_|',S t r B u f S i z(eP) ) ;
                      S t r D i s p o s(eP ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 407

                 _____________________________________________________________________________________________20.7.___PCHAR_FUNCTIO*
 *NS__________________
                 20.7.4        StrDispose

Declaration:      Procedure  StrDispose(var  Str:    PChar);

Description:      StrDispose frees any memory allocated for Str.  This function will only function correctly
                 if  Str has been allocated using StrAlloc (407) from the SYSUTILS unit.

       Errors:    If an invalid pointer is passed, or a pointer not allocated with StrAlloc, an error may occur.

     See also:    StrBufSize (407), StrAlloc (407), StrDispose (359)


                 For an example, see StrBufSize (407).
                 20.7.5        StrPCopy

Declaration:      Function  StrPCopy(Dest:    PChar;  Source:    string):    PChar;

Description:      StrPCopy Converts the Ansistring in Source to a Null-terminated string, and copies it to
                 Dest.  Dest needs enough room to contain the string Source, i.e.  Length(Source)+1 bytes.

       Errors:    No checking is performed to see whether Dest points to enough memory to contain Source.

     See also:    StrPLCopy (408), StrPCopy (365)


                 For an example, see StrPCopy (365).
                 20.7.6        StrPLCopy

Declaration:      Function  StrPLCopy(Dest:    PChar;  Source:    string;  MaxLen:    cardinal):    PChar;

Description:      StrPLCopy Converts maximally MaxLen characters of the Ansistring in Source to a Null-
                 terminated string, and copies it to Dest.  Dest needs enough room to contain the characters.

       Errors:    No  checking  is  performed  to  see  whether  Dest  points  to  enough  memory  to  contain  L
                 characters of  Source.

       Errors:

     See also:    StrPCopy (408).
                 20.7.7        StrPas

Declaration:      Function  StrPas(Str:    PChar):    string;

Description:      Converts  a  null  terminated  string  in  Str  to  an  Ansitring,  and  returns  this  string.   This
                 string is NOT truncated at 255 characters as is the

       Errors:    None.

     See also:    StrPas (364).


                 For an example, see StrPas (364).



                                                                                 408

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8          String  handling  functions



                 20.8.1        AdjustLineBreaks

Declaration:      Function  AdjustLineBreaks(const  S:  string):    string;

Description:      AdjustLineBreaks will change all #13 characters with #13#10 on Windows NT and dos.
                 On linux, all #13#10 character pairs are converted to #10 and single #13 characters also.

       Errors:    None.

     See also:    AnsiCompareStr (409), AnsiCompareText (410)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example48      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A d j u s t L i n e B r e a kfsu n c t i o n}


                 Uses     s y s u t i l;s


                 Const
                    S  =   ' T h i s|_|i s|_|a|_|s t r i n'g#13 ' w i t h|_|embedded    ' #10  ' l i n e f e e d|_|and'+
                             #13  ' CR  |_|c h a r a c t e r's;


                 Begin
                    W r i t e l n ( A d j u s t L i n e B r e a k(sS) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.2        AnsiCompareStr

Declaration:      Function  AnsiCompareStr(const  S1,  S2:    string):    integer;

Description:      AnsiCompareStr compares two strings and returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 the  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                 characters.  Contrary to AnsiCompareText (410), the comparision is case sensitive.

       Errors:    None.

     See also:    AdjustLineBreaks (409), AnsiCompareText (410)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example49      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i C o m p a r e S t rf u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  S t r i n g) ;


                 Var   R   :   L o n g i n t;


                 b e g i n



                                                                                 409

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                    R := AnsiCompareStr           (S1  , S2 ) ;
                    Write     (  ' " ',S1  , ' " |_|i s|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' " ', S2 , ' " ' ) ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' one  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|t a l l|_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.3        AnsiCompareText

Declaration:      Function  AnsiCompareText(const  S1,  S2:    string):    integer;

Description:

Description:      AnsiCompareText compares two strings and returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 the  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                 characters.  Contrary to AnsiCompareStr (409), the comparision is case insensitive.

       Errors:    None.

     See also:    AdjustLineBreaks (409), AnsiCompareText (410)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example49      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i C o m p a r e T e x tf u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  S t r i n g) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R := AnsiCompareText            (S1  ,S2  ) ;
                    Write     (  ' " ',S1  , ' " |_|i s|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                                                                                 410

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' " ', S2 , ' " ' ) ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' one  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|t a l l|_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.4        AnsiExtractQuotedStr

Declaration:      Function  AnsiExtractQuotedStr(var  Src:    PChar;  Quote:    Char):    string;

Description:      AnsiExtractQuotedStr Returns Src as a string,, with Quute characters removed from the
                 beginning  and  end  of  the  string,  and  double  Quote  characters  replaced  by  a  single  Quote
                 characters.  As such, it revereses the action of  AnsiQuotedStr (412).

       Errors:    None.

     See also:    AnsiQuotedStr (412)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example51      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i Q u o t e d S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   A n s i S t r i n;g


                 Begin
                    S :=  'He  |_|s a i d|_|"H e l l"o|_|and|_|w a l k e d|_|on';
                    S :=  A n s i Q u o t e d S t(rPchar   (S ) , ' " ') ;
                    W r i t e l n ( S ) ;
                    W r i t e l n(A n s i E x t r a c t Q u o t e d S(tPrchar  ( S ) , ' " ') ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.5        AnsiLastChar

Declaration:      Function  AnsiLastChar(const  S:  string):    PChar;

Description:      This function returns a pointer to the last character of  S. Since multibyte characters are
                 not yet supported, this is the same as @S[Length(S)]).

       Errors:    None.

     See also:    AnsiStrLastChar (414)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example52      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i L a s t C h a rf u n c t i o n}


                 Uses     s y s u t i l;s
                                                                                 411

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 Var    S  :   A n s i S t r i n;g
                        L  :   L o n g i n t;


                 Begin
                    S :=  'T h i s|_|i s|_|an|_|a n s i s t r i n.g';
                    W r i t e l n ( ' L a s t|_|c h a r a c t e|r_|o|f_|S|_|i|s_|: |_|',A n s i L a s t C h(aSr) ) ;
                    L :=  L o n g i n t(A n s i L a s t C h a(rS))-  L o n g i n t(@S  [ 1 ] ) + 1 ;
                    W r i t e l n ( ' L e n g t h|_|o|f_|S|_|i|s_|: |_|',L) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.6        AnsiLowerCase

Declaration:      Function  AnsiLowerCase(const  s:    string):    string;

Description:      AnsiLowerCase  converts  the  string  S  to  lowercase  characters  and  returns  the  resulting
                 string.   It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so
                 spcial characters are converted correctly as well.

                 Remark On linux, no language setting is taken in account yet.

       Errors:    None.

     See also:    AnsiUpperCase (418), AnsiStrLower (416), AnsiStrUpper (417)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example53      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i L o w e r C a s ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                   W r i t e l n( S , ' |_|-> |_|',AnsiLowerCase         (S ) )
                 end  ;


                 Begin
                    T e s t i t( 'AN  |_|UPPERCASE     |_|STRING   ' ) ;
                    T e s t i t( 'Some   |_|mixed   |_|S T r i n'g) ;
                    T e s t i t( 'a |_|l o w e r c a s|e_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.7        AnsiQuotedStr

Declaration:      Function  AnsiQuotedStr(const  S:  string;  Quote:    char):    string;

Description:      AnsiQuotedString quotes the string S and returns the result.  This means that it puts the
                 Quote character at both the beginning and end of the string and replaces any occurrence of
                 Quote in S with 2 Quote characters.  The action of  AnsiQuotedString can be reversed by
                 AnsiExtractQuotedStr (411).

       Errors:    None.

     See also:    AnsiExtractQuotedStr (411)


                 For an example, see AnsiExtractQuotedStr (411)



                                                                                 412

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.8        AnsiStrComp

Declaration:      Function  AnsiStrComp(S1,  S2:    PChar):    integer;

Description:      AnsiStrComp compares 2 PChar strings, and returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 The comparision of the two strings is case-sensitive.  The function does not yet take interna-
                 tionalization settings into account.

       Errors:    None.

     See also:    AnsiCompareText (410), AnsiCompareStr (409)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example54      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  AnsiStrComp          f u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  Pchar    ) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R := AnsiStrComp         (S1  ,S2  ) ;
                    Write     (  ' " ',S1  , ' " |_|i s|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' " ', S2 , ' " ' ) ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' one  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|t a l l|_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.9        AnsiStrIComp

Declaration:      Function  AnsiStrIComp(S1,  S2:    PChar):    integer;

Description:      AnsiStrIComp compares 2 PChar strings, and returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                                                                                 413

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 The comparision of the two strings is case-insensitive.  The function does not yet take inter-
                 nationalization settings into account.

       Errors:    None.

     See also:    AnsiCompareText (410), AnsiCompareStr (409)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example55      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i S t r I C o m pf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  Pchar    ) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R :=  A n s i S t r I C o m(pS1 ,S2  ) ;
                    Write     (  ' " ',S1  , ' " |_|i s|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' " ', S2 , ' " ' ) ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' one  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|t a l l|_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.10         AnsiStrLastChar

Declaration:      function  AnsiStrLastChar(Str:    PChar):    PChar;

Declaration:      AnsiStrLastChar  returns  a  pointer  to  the  last  character  of  Str.    Since  multibyte
                 characters  are  not  yet  supported,  this  is  the  same  as  StrEnd(Str)-1.

       Errors:    None.

     See also:    AnsiLastChar (411)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example58      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i S t r L a s t C h a rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var   P   :   Pchar   ;
                        L  :   L o n g i n t;
                                                                                 414

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 Begin
                    P :=  'T h i s|_|i s|_|an|_|PChar  |_|s t r i n g. ';
                    W r i t e l n ( ' L a s t|_|c h a r a c t e|r_|o|f_|P|_|i|s_|: |_|',A n s i S t r L a s t C(hPa)r) ;
                    L :=  L o n g i n t(A n s i S t r L a s t C h a(rP))- L o n g i n t(P )+1;
                    W r i t e l n ( ' L e n g t h|_|o|f_|P|_|(,'P ,' ) |_|i s|_|: |_|',L) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.11         AnsiStrLComp

Declaration:      Function  AnsiStrLComp(S1,  S2:    PChar;  MaxLen:    cardinal):    integer;

Description:      AnsiStrLComp  compares  the  first  Maxlen  characters  of  2  PChar  strings,  S1  and  S2,  and
                 returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 The comparision of the two strings is case-sensitive.  The function does not yet take interna-
                 tionalization settings into account.

       Errors:    None.

     See also:    AnsiCompareText (410), AnsiCompareStr (409)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example56      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  AnsiStrLComp          f u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  Pchar    ;  L   :  l o n g i n t) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R := AnsiStrLComp         ( S1  ,S2  ,L ) ;
                    Write     (  'F i r s t|_|',L , ' |_|c h a r a c t e r|s_|o|f_|",'S1, ' " |_|a r e|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' t h o s e|_|o f|_|",'S2 , ' " ') ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g, 2 5 5 ) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|S t r i n'g, 4 ) ;
                    T e s t i t( 'One   |_|s t r i n'g,' 1 |_|s t r i n'g, 0 ) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n g. ', 9 ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 415

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.12         AnsiStrLIComp

Declaration:      Function  AnsiStrLIComp(S1,  S2:    PChar;  MaxLen:    cardinal):    integer;

Description:      AnsiStrLIComp  compares  the  first  Maxlen  characters  of  2  PChar  strings,  S1  and  S2,  and
                 returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 The comparision of the two strings is case-insensitive.  The function does not yet take inter-
                 nationalization settings into account.

       Errors:    None.

     See also:    AnsiCompareText (410), AnsiCompareStr (409)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example57      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i S t r L I C o m pf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  Pchar    ;  L   :  l o n g i n t) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R :=  A n s i S t r L I C o m(pS1, S2  ,L ) ;
                    Write     (  'F i r s t|_|',L , ' |_|c h a r a c t e r|s_|o|f_|",'S1, ' " |_|a r e|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' t h o s e|_|o f|_|",'S2 , ' " ') ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g, 2 5 5 ) ;
                    T e s t i t( 'ONE   |_|STRING   ', ' one  |_|S t r i n'g, 4 ) ;
                    T e s t i t( 'One   |_|s t r i n'g,' 1 |_|STRING   ' , 0 ) ;
                    T e s t i t( 'One   |_|STRING   ', ' one  |_|s t r i n g. ', 9 ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.13         AnsiStrLower

Declaration:      Function  AnsiStrLower(Str:    PChar):    PChar;

Description:      AnsiStrLower  converts  the  PChar  Str  to  lowercase  characters  and  returns  the  resulting
                 pchar.  Note that Str itself is modified, not a copy, as in the case of  AnsiLowerCase (412).
                 It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so  spcial
                 characters are converted correctly as well.

                 Remark On linux, no language setting is taken in account yet.



                                                                                 416

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
       Errors:    None.

     See also:    AnsiStrUpper (417), AnsiLowerCase (412)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example59      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i S t r L o w e rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( S   :  Pchar    ) ;


                 b e g i n
                   W r i t e l n( S , ' |_|-> |_|',A n s i S t r L o w e(rS) )
                 end  ;


                 Begin
                    T e s t i t( 'AN  |_|UPPERCASE     |_|STRING   ' ) ;
                    T e s t i t( 'Some   |_|mixed   |_|S T r i n'g) ;
                    T e s t i t( 'a |_|l o w e r c a s|e_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.14         AnsiStrUpper

Declaration:      Function  AnsiStrUpper(Str:    PChar):    PChar;

Description:      AnsiStrUpper  converts  the  PChar  Str  to  uppercase  characters  and  returns  the  resulting
                 string.  Note that Str itself is modified, not a copy, as in the case of  AnsiUpperCase (418).
                 It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so  spcial
                 characters are converted correctly as well.

                 Remark On linux, no language setting is taken in account yet.

       Errors:    None.

     See also:    AnsiUpperCase (418), AnsiStrLower (416), AnsiLowerCase (412)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example60      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i S t r U p p e rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( S   :  Pchar    ) ;


                 b e g i n
                   W r i t e l n( S , ' |_|-> |_|',A n s i S t r U p p e(rS) )
                 end  ;


                 Begin
                    T e s t i t( 'AN  |_|UPPERCASE     |_|STRING   ' ) ;
                    T e s t i t( 'Some   |_|mixed   |_|S T r i n'g) ;
                    T e s t i t( 'a |_|l o w e r c a s|e_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________


                                                                                 417

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.15         AnsiUpperCase

Declaration:      Function  AnsiUpperCase(const  s:    string):    string;

Description:      AnsiUpperCase  converts  the  string  S  to  uppercase  characters  and  returns  the  resulting
                 string.   It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so
                 spcial characters are converted correctly as well.

                 Remark On linux, no language setting is taken in account yet.

       Errors:    None.

     See also:    AnsiStrUpper (417), AnsiStrLower (416), AnsiLowerCase (412)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example60      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A n s i U p p e r C a s ef u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                   W r i t e l n( S , ' |_|-> |_|',AnsiUpperCase         (S ) )
                 end  ;


                 Begin
                    T e s t i t( 'AN  |_|UPPERCASE     |_|STRING   ' ) ;
                    T e s t i t( 'Some   |_|mixed   |_|S T r i n'g) ;
                    T e s t i t( 'a |_|l o w e r c a s|e_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.16         AppendStr

Declaration:      Procedure  AppendStr(var  Dest:    String;  const  S:  string);

Description:      AppendStr appends S to Dest.

                 This function is provided for Delphi compatibility only, since it is completely equivalent to
                 Dest:=Dest+S.

       Errors:    None.

     See also:    AssignStr (419),NewStr (283), DisposeStr (284)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example62      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A p p e n d S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   A n s i S t r i n;g


                 Begin
                    S :=  'T h i s|_|i s|_|an|_|';
                    AppendStr       (S , ' A n s i S t r i n'g) ;
                    W r i t e l n ( 'S  |_|= |_|"',S, ' " ') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 418

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.17         AssignStr

Declaration:      Procedure  AssignStr(var  P:  PString;  const  S:  string);

Description:      AssignStr allocates S to P. The old value of  P is disposed of.

                 This function is provided for Delphi compatibility only.  AnsiStrings are managed on the
                 heap and should be preferred to the mechanism of dynamically allocated strings.

       Errors:    None.

     See also:    NewStr (283), AppendStr (418), DisposeStr (284)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example63      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  A s s i g n S t rf u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Var   P   :   P S t r i n g;


                 Begin
                  P :=  NewStr    ( 'A  |_|f i r s|t_|A n s i S t r i'n)g;
                   W r i t e l n( ' B e f o r e: |_|P|_|= |_|"',P^ ,' " ') ;
                   A s s i g n S t(rP ,' A |_|Second   |_|a n s i s t r i n'g) ;
                   W r i t e l n( ' A f t e r|_|: |_|P|_|= |_|"',P^ ,' " ') ;
                   D i s p o s e S t(rP ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.18         BCDToInt

Declaration:      Function  BCDToInt(Value:    integer):    integer;

Description:      BCDToInt converts a BCD coded integer to a normal integer.

       Errors:    None.

     See also:    StrToInt (436), IntToStr (432)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example64      ;


                 {  T h i s  program       d e m o n s t r a t e st h e BCDToInt        f u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t (   L  :   l o n g i n t) ;
                 b e g i n
                    W r i t e l n ( L ,' |_|-> |_|',BCDToInt      (L ) ) ;
                 end  ;


                 Begin
                    T e s t i t( 1 0 ) ;
                    T e s t i t( 1 0 0 ) ;
                    T e s t i t( 1 0 0 0 ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________

                                                                                 419

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.19         CompareMem

Declaration:      Function  CompareMem(P1,  P2:    Pointer;  Length:    cardinal):    integer;

Description:      CompareMem compares, byte by byte, 2 memory areas pointed to by P1 and P2, for a length
                 of  L bytes.

                 It returns the following values:

                 <0if at some position the byte at P1 is less than the byte at the same postion at P2.

                 0if all L bytes are the same.

                 3

       Errors:

     See also:
                 20.8.20         CompareStr

Declaration:      Function  CompareStr(const  S1,  S2:    string):    Integer;

Description:      CompareStr compares two strings, S1 and S2, and returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 The comparision of the two strings is case-sensitive.  The function does not take internation-
                 alization settings into account, it simply compares ASCII values.

       Errors:    None.

     See also:    AnsiCompareText (410), AnsiCompareStr (409), CompareText (421)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example65      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  CompareStr         f u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  S t r i n g) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R := CompareStr        ( S1 , S2  ) ;
                    Write     (  ' " ',S1  , ' " |_|i s|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' " ', S2 , ' " ' ) ;
                 end  ;

                                                                                 420

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' one  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|t a l l|_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.21         CompareText

Declaration:      Function  CompareText(const  S1,  S2:    string):    integer;

Description:      CompareText compares two strings, S1 and S2, and returns the following result:

                 <0if  S1<S2.

                 0if  S1=S2.

                 >0 if  S1>S2.

                 The comparision of the two strings is case-insensitive.  The function does not take interna-
                 tionalization settings into account, it simply compares ASCII values.

       Errors:    None.

     See also:    AnsiCompareText (410), AnsiCompareStr (409), CompareStr (420)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example66      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  CompareText          f u n c t i o n}
                 {$H  +}


                 Uses     s y s u t i l;s


                 Procedure        T e s t I t ( S1  ,S2    :  S t r i n g) ;


                 Var   R   :   L o n g i n t;


                 b e g i n
                    R := CompareText         (S1  ,S2  ) ;
                    Write     (  ' " ',S1  , ' " |_|i s|_|') ;
                    I f  R <0   then
                        w r i t e ( ' l e s s|_|t h a n|_|')
                    e l s e  I f  R =0   then
                        Write     ( ' e q u a l|_|to|_|')
                    e l s e
                        Write     ( ' l a r g e r|_|t h a|n_|') ;
                    W r i t e l n ( ' " ', S2 , ' " ' ) ;
                 end  ;


                 Begin
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s m a l l e|r_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' one  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|s t r i n'g) ;
                    T e s t i t( 'One   |_|s t r i n'g,' One  |_|t a l l|_|s t r i n'g) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 421

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.22         DisposeStr

Declaration:      Procedure  DisposeStr(S:  PString);

Description:      DisposeStr  removes  the  dynamically  allocated  string  S  from  the  heap,  and  releases  the
                 occupied memory.

                 This function is provided for Delphi compatibility only.  AnsiStrings are managed on the
                 heap and should be preferred to the mechanism of dynamically allocated strings.

       Errors:    None.

     See also:    NewStr (283), AppendStr (418), AssignStr (419)


                 For an example, see DisposeStr (284).
                 20.8.23         FloatToStr

Declaration:      Function  FloatToStr(Value:    Extended):    String;

Description:      FloatToStr converts the floating point variable Value to a string representation.  It will
                 choose the shortest possible notation of the two following formats:

                 Fixed format        will represent the string in fixed notation,

                 Decimal format          will represent the string in scientific notation.

                 (more information on these formats can be found in FloatToStrF (423)) FloatToStr is com-
                 pletely equivalent to a FloatToStrF(Value,  ffGeneral,  15,  0); call.

       Errors:    None.

     See also:    FloatToStrF (423)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example67      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F l o a t T o S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( V a l u e  :  E x t e n d e d) ;


                 b e g i n
                    W r i t e l n ( V a l u e,' |_|-> |_|',F l o a t T o S t(rV a l u e) ) ;
                    W r i t e l n (-  V a l u e,' |_|-> |_|',F l o a t T o S t(r-V a l u e) ) ;
                 end  ;


                 Begin
                    T e s t i t ( 0 . 0 ) ;
                    T e s t i t ( 1 . 1 ) ;
                    T e s t i t ( 1 . 1e -3);
                    T e s t i t ( 1 . 1e -20);
                    T e s t i t ( 1 . 1e -200);
                    T e s t i t ( 1 . 1e +3);
                    T e s t i t ( 1 . 1e +20);
                    T e s t i t ( 1 . 1e +200);
                _End__.____________________________________________________________________________________________________________*
 *_____________


                                                                                 422

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.24         FloatToStrF

Declaration:      Function  FloatToStrF(Value:    Extended;  format:    TFloatFormat;  Precision,  Digits:
                 Integer):    String;

Description:      FloatToStrF converts the floating point number value to a string representation, according
                 to the settings of the parameters Format, Precision and Digits.

                 The meaning of the Precision and Digits parameter depends on the Format parameter.
                 The format is controlled mainly by the Format parameter.  It can have one of the following
                 values:

                 ffcurrency     Money format.  Value is converted to a string using the global variables CurrencyString,
                       CurrencyFormat and NegCurrencyFormat.  The Digits paramater specifies the num-
                       ber of digits following the decimal point and should be in the range -1 to 18.  If Digits
                       equals -1, CurrencyDecimals is assumed.  The Precision parameter is ignored.

                 ffExponent       Scientific format.  Value is converted to a string using scientific notation:  1 digit
                       before the decimal point, possibly preceded by a minus sign if  Value is negative.  The
                       number of digits after the decimal point is controlled by Precision and must lie in the
                       range 0 to 15.

                 ffFixed   Fixed point format.  Value is converted to a string using fixed point notation.  The
                       result is composed of all digits of the integer part of  Value, preceded by a minus sign
                       if  Value  is  negative.   Following  the  integer  part  is  DecimalSeparator  and  then  the
                       fractional  part  of  Value,  rounded  off  to  Digits  numbers.  If  the  number  is  too  large
                       then the result will be in scientific notation.

                 ffGeneral     General number format.  The argument is converted to a string using ffExponent
                       or ffFixed format, depending on wich one gives the shortest string.  There will be no
                       trailing zeroes.  If  Value is less than 0.00001 or if the number of decimals left of the
                       decimal point is larger than Precision then scientific notation is used, and Digits is
                       the minimum number of digits in the exponent.  Otherwise Digits is ignored.

                 ffnumber      Is the same as ffFixed, except that thousand separators are inserted in the resultig
                       string.

       Errors:    None.

     See also:    FloatToStr (422), FloatToText (424)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example68      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F l o a t T o S t r Ff u n c t i o n}


                 Uses     s y s u t i l;s


                 Const     Fmt    :   Array     [ T F l o a t F o r m a]t of    s t r i n g[ 1 0 ]  =
                                ( ' g e n e r a l', 'e x p o n e n t', ' f i x e d', 'number     ' ,' C u r r e n c y') ;


                 Procedure        T e s t i t ( V a l u e  :    E x t e n d e d) ;


                 Var    I ,J   :  l o n g i n t;
                        FF   :  T F l o a t F o r m a;t


                 b e g i n
                    For    I :=5    to   1 5  do
                        For    J:=1    to   4   do
                           For    FF  := f f g e n e r a l to   f f c u r r e n c ydo
                               b e g i n



                                                                                 423

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                               Write     ( V a l u e, ' (P r e c: |_|',I : 2 ,' , |_|Dig: |_|',J , ' , |_|fmt |_|: |_|',Fmt[ f f ] *
 *,' ) |_|: |_|') ;
                               W r i t e l n( F l o a t T o S t r f(V a l u e,FF , I ,J ) ) ;
                               Write     (-  V a l u e,' ( P r e c: |_|',I: 2 , ' , |_|Dig: |_|',J , ' , |_|fmt|_|: |_|',Fmt [ f f]*
 * , ' ) |_|: |_|') ;
                               W r i t e l n( F l o a t T o S t r(f- V a l u e,FF  , I ,J ) ) ;
                               end  ;
                 end  ;


                 Begin
                    T e s t i t ( 1 . 1 ) ;
                    T e s t i t ( 1 . 1E1  ) ;
                    T e s t i t ( 1 . 1E -1);
                    T e s t i t ( 1 . 1E5  ) ;
                    T e s t i t ( 1 . 1E -5);
                    T e s t i t ( 1 . 1E10   ) ;
                    T e s t i t ( 1 . 1E -10);
                    T e s t i t ( 1 . 1E15   ) ;
                    T e s t i t ( 1 . 1E -15);
                    T e s t i t ( 1 . 1E100    ) ;
                    T e s t i t ( 1 . 1E -100);
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.25         FloatToText

Declaration:      Function  FloatToText(Buffer  :    Pchar;Value:    Extended;  Format:    TFloatFormat;
                 Precision,  Digits:    Integer):    Longint;

Description:      FloatToText  converts  the  floating  point  variable  Value  to  a  string  representation  and
                 stores it in Buffer.  The conversion is giverned by format, Precisison and Digits.  more
                 information on these parameters can be found in FloatToStrF (423).  Buffer should point to
                 enough space to hold the result.  No checking on this is performed.

                 The result is the number of characters that was copied in Buffer.

       Errors:    None.

     See also:    FloatToStr (422), FloatToStrF (423)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example68      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  F l o a t T o S t r Ff u n c t i o n}


                 Uses     s y s u t i l;s


                 Const     Fmt    :   Array     [ T F l o a t F o r m a]t of    s t r i n g[ 1 0 ]  =
                                ( ' g e n e r a l', 'e x p o n e n t', ' f i x e d', 'number     ' ,' C u r r e n c y') ;


                 Procedure        T e s t i t ( V a l u e  :    E x t e n d e d) ;


                 Var    I ,J   :  l o n g i n t;
                        FF   :  T F l o a t F o r m a;t
                        S  :   S h o r t S t r i n;g


                 b e g i n
                    For    I :=5    to   1 5  do
                        For    J:=1    to   4   do
                           For    FF  := f f g e n e r a l to   f f c u r r e n c ydo
                               b e g i n



                                                                                 424

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                               Write     ( V a l u e, ' (P r e c: |_|',I : 2 ,' , |_|Dig: |_|',J , ' , |_|fmt |_|: |_|',Fmt[ f f ] *
 *,' ) |_|: |_|') ;
                               S e t L e n g t(hS , FloatToText         ( @S  [ 1 ] ,V a l u e,FF  ,I , J ) ) ;
                               W r i t e l n( S ) ;
                               Write     (-  V a l u e,' ( P r e c: |_|',I: 2 , ' , |_|Dig: |_|',J , ' , |_|fmt|_|: |_|',Fmt [ f f]*
 * , ' ) |_|: |_|') ;
                               S e t L e n g t(hS , FloatToText         ( @S  [ 1 ] , -V a l u e,FF , I , J ) ) ;
                               W r i t e l n( S ) ;
                               end  ;
                 end  ;


                 Begin
                    T e s t i t ( 1 . 1 ) ;
                    T e s t i t ( 1 . 1E1  ) ;
                    T e s t i t ( 1 . 1E -1);
                    T e s t i t ( 1 . 1E5  ) ;
                    T e s t i t ( 1 . 1E -5);
                    T e s t i t ( 1 . 1E10   ) ;
                    T e s t i t ( 1 . 1E -10);
                    T e s t i t ( 1 . 1E15   ) ;
                    T e s t i t ( 1 . 1E -15);
                    T e s t i t ( 1 . 1E100    ) ;
                    T e s t i t ( 1 . 1E -100);
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.26         FmtStr

Declaration:      Procedure  (Var  Res:    String;  Const  Fmt  :    String;  Const  args:    Array  of  const);

Description:      FmtStr calls Format (425) with Fmt and Args as arguments, and stores the result in Res.
                 For more information on how the resulting string is composed, see Format (425).

       Errors:    In case of error, a EConvertError exception is raised.

     See also:    Format (425), FormatBuf  (431).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example70      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  FmtStr      f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   A n s i S t r i n;g


                 Begin
                    S :=  ' ';
                    FmtStr      ( S , 'For   |_|some |_|n i c e|_|e x a m p l e|s_|o|f_|f o m a t t i|n_g|s|e_e|%s. ', ['Format    *
 * ' ] ) ;
                    W r i t e l n ( S ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.27         Format

Declaration:      Function  Format(Const  Fmt  :    String;  const  Args  :    Array  of  const)  :    String;

Description:      Format replaces all placeholders inFmt with the arguments passed in Args and returns the
                 resulting string.  A placeholder looks as follows:


                 '%'  [Index':']  ['-']  [Width]  ['.'  Precision]  ArgType



                                                                                 425

_________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS_________________________*
 *___
elements between single quotes must be typed as shown without the quotes, and elements
between square brackets [  ] are optional.  The meaning of the different elements is shown
below:

'%'  starts the placeholder.  If you want to insert a literal % character, then you must insert
      two of them :  %%.

Index ':'    takes the Index-th element in the argument array as the element to insert.

'-'tells Format to left-align the inserted text.  The default behaviour is to right-align inserted
      text.  This can only take effect if the Width element is also specified.

Width     the  inserted  string  must  have  at  least  have  Width  characters.   If  not,  the  inserted
      string will be padded with spaces.  By default, the string is left-padded, resulting in a
      right-aligned string.  This behaviour can be changed by the '-' character.

'.'  Precision     Indicates the precision to be used when converting the argument.  The exact
      meaning of this parameter depends on ArgType.

The Index, Width and Precision parameters can be replaced by *, in which case their value
will be read from the next element in the Args array.  This value must be an integer, or an
EConvertError exception will be raised.

The  argument  type  is  determined  from  ArgType.   It  can  have  one  of  the  following  values
(case insensitive):

D Decimal format.  The next argument in the Args array should be an integer.  The argument
      is converted to a decimal string,.  If precision is specified, then the string will have at
      least Precision digits in it.  If needed, the string is (left) padded with zeroes.

E scientific format.  The next argument in the Args array should be a Floating point value.
      The  argument  is  converted  to  a  decimal  string  using  scientific  notation,  using  Float-
      ToStrF (423), where the optional precision is used to specify the total number of dec-
      imals.   (defalt  a  valueof  15  is  used).   The  exponent  is  formatted  using  maximally  3
      digits.

      In short, the E specifier formats it's arguument as follows:

      FloatToStrF(Argument,ffexponent,Precision,3)

F fixed point format.  The next argument in the Args array should be a floating point value.
      The  argument  is  converted  to  a  decimal  string,  using  fixed  notation  (see  FloatToStrF
      (423)).  Precision indicates the number of digits following the decimal point.

      In short, the F specifier formats it's arguument as follows:

      FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)

G General number format.  The next argument in the Args array should be a floating point
      value.   The  argument  is  converted  to  a  decimal  string  using  fixed  point  notation  or
      scientific notation, depending on which gives the shortest result.  Precision is used to
      determine the number of digits after the decimal point.

      In short, the G specifier formats it's arguument as follows:

      FloatToStrF(Argument,ffGeneral,Precision,3)

M  Currency format.  the next argument in the varArgs array must be a floating point value.
      The  argument  is  converted  to  a  decimal  string  using  currency  notation.  This  means
      that fixed-point notation is used, but that the currency symbol is appended.  If precision
      is specified,  then then it overrides the CurrencyDecimals global variable used in the
      FloatToStrF (423)

      In short, the M specifier formats it's arguument as follows:

      FloatToStrF(Argument,ffCurrency,9999,Precision)



                                                                426

            _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS_____________*
 *_______________
            N Number format.  This is the same as fixed point format, except that thousand separators
                  are inserted in the resulting string.

            P Pointer format.  The next argument in the Args array must be a pointer (typed or untyped).
                  The pointer value is converted to a string of length 8, representing the hexadecimal value
                  of the pointer.

            S String  format.   The  next  argument  in  the  Args  array  must  be  a  string.   The  argument
                  is simply copied to the result string.  If  Precision is specified,  then only  Precision
                  characters are copied to the result string.

            X hexadecimal  format.   The  next  argument  in  the  Args  array  must  be  an  integer.   The
                  argument is converted to a hexadecimal string with just enough characters to contain
                  the  value  of  the  integer.   If  Precision  is  specified  then  the  resulting  hexadecimal
                  representation will have at least Precision characters in it (with a maximum value of
                  32).

  Errors:    In case of error, an EConversionError exception is raised.  Possible errors are:

                1.Errors in the format specifiers.

                2.The next argument is not of the type needed by a specifier.

                3.The number of arguments is not sufficient for all format specifiers.

See also:    FormatBuf  (431)


           ________________________________________________________________________________________________________________________*
 *________
            Program       e x a m p l e 7;1


            {$mode      o b j f p c}


            {  T h i s  program       d e m o n s t r a t e st h e  Format      f u n c t i o n}


            Uses     s y s u t i l;s


            Var   P   :   P o i n t e r;
                   fmt  , S  :   s t r i n g;


            Procedure        T e s t I n t e g e;r


            b e g i n
               Try
                   Fmt  := '[%   d ] ';S :=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  :=  ' [ % % ] ';S:=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  := '[%10    d ] '; S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
                   fmt  :=  ' [ % . 4d] '; S := Format      ( fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  :=  ' [ % 1 0 .d4 ] ';S :=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  :=  ' [ % 0 :d] '; S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  :=  ' [ % 0 : 1d0 ] ';S :=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  :=  ' [ % 0 : 1 0 .d4] '; S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  := '[%0:-10      d ] ' ;S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  :=  ' [ % 0 : - 1 0 .d4] '; S:=  Format      ( fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
                   Fmt  := '[%-*.*     d  ] ';S :=  Format      ( fmt  , [ 4 , 5 , 1 0 ] )w;r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s*
 *) ;
               e x c e p t
                  On    E  :   E x c e p t i o ndo
                      b e g i n
                      W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
                      end   ;
               end   ;
               w r i t e l n ( ' P r e s s|_|e n t e'r) ;



                                                                            427

_________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS_________________________*
 *___
   r e a d l n;
end  ;


Procedure        T e s t H e x a D e c i m a;l


b e g i n
   t r y
       Fmt  := '[%   x ] ';S :=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%10    x ] '; S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 1 0 . 4x] ';S :=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 :x] '; S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : 1 0x] ';S :=  Format      ( Fmt  , [ 1 0 ] ) ;w r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : 1 0 .x4] '; S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%0:-10      x ] ' ;S := Format      ( Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : - 1 0 .x4] '; S:=  Format      ( fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%-*.*      x ] ';S :=  Format      ( fmt  , [ 4 , 5 , 1 0 ] )w;r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s) ;
   e x c e p t
      On    E  :   E x c e p t i o ndo
          b e g i n
          W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
          end   ;
   end   ;
   w r i t e l n ( ' P r e s s|_|e n t e'r) ;
   r e a d l n;
end  ;


Procedure        T e s t P o i n t e;r


b e g i n
   P :=  P o i n t e r( 1 2 3 4 5 6 7 ) ;
   t r y
       Fmt  :=  ' [ 0x% p ] '; S := Format      ( Fmt   , [P ] ) ;w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x%10  p  ] ';S :=  Format      ( Fmt  , [P  ] ) ;w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x%10.4    p ] '; S := Format      ( Fmt   , [P ] ) ;w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x%0:  p  ] ';S :=  Format      ( Fmt  , [P  ] ) ;w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x%0:10    p ] '; S := Format      ( Fmt   , [P ] ) ;w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x% 0 : 1 0 . 4p ] ';S :=  Format      ( Fmt  , [P ] ) ; w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x%0:-10     p ] '; S:=  Format      ( Fmt  , [P  ] ) ;w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ 0x%0:-10.4      p ] ' ;S := Format      ( fmt   , [P ] ) ;w r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%-*.*     p  ] ';S :=  Format      ( fmt  , [ 4 , 5 ,P] ) ; w r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
   e x c e p t
      On    E  :   E x c e p t i o ndo
          b e g i n
          W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
          end   ;
   end   ;
   w r i t e l n ( ' P r e s s|_|e n t e'r) ;
   r e a d l n;
end  ;


Procedure        T e s t S t r i n g;


b e g i n
   t r y
       Fmt  := '[%   s ] ';S :=  Format    ( fmt   , [' T h i s|_|i s|_|a|_|s t r i'n]g) ;W r i t e l n(fmt   : 1 2 ,'=> |_|', s ) ;
       fmt  :=  ' [ % 0 :s] '; s := Format     ( fmt  , [' T h i s|_|i s|_|a|_|s t r i n'g] ) ;W r i t e l(nfmt  : 1 2 ,'=> |_|' ,s*
 * ) ;
       fmt  :=  ' [ % 0 : 1 8s] '; s:=  Format    ( fmt   , [' T h i s|_|i s|_|a|_|s t r i'n]g) ;W r i t e l n(fmt   : 1 2 ,'=> |_|*
 *', s ) ;
       fmt  := '[%0:-18      s ] ' ;s := Format     ( fmt  , [ 'T h i s|_|i s|_|a|_|s t r i n'g] ) ;W r i t e l(nfmt  : 1 2 ,'=> |_*
 *|' , s ) ;
                                                                428

_________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS_________________________*
 *___
       fmt  :=  ' [ % 0 : 1 8 . 1s2] '; s:=  Format     (fmt   , [' T h i s|_|i s|_|a|_|s t r i n'g] ) ;W r i t e l(nfmt  : 1 2 ,'=*
 *> |_|' ,s ) ;
       fmt  := '[%-*.*      s ] '; s:=  Format    ( fmt   , [ 1 8 , 1 2',T h i s|_|i s|_|a|_|s t r i n'g] ) ;W r i t e l(nfmt  : 1 *
 *2 ,'=> |_|' ,s@
   e x c e p t
      On    E  :   E x c e p t i o ndo
          b e g i n
          W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
          end   ;
   end   ;
   w r i t e l n ( ' P r e s s|_|e n t e'r) ;
   r e a d l n;
end  ;


Procedure        T e s t E x p o n e n t i a;l


b e g i n
   Try
       Fmt  := '[%   e ] ';S :=  Format      ( Fmt  , [ 1 . 2 3 4 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%10    e ] '; S := Format      ( Fmt   , [ 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 1 0 . 4e] ';S :=  Format      ( Fmt  , [ 1 . 2 3 4 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 :e] '; S := Format      ( Fmt   , [ 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : 1 0e] ';S :=  Format      ( Fmt  , [ 1 . 2 3 4 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : 1 0 .e4] '; S := Format      ( Fmt   , [ 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%0:-10      e ] ' ;S := Format      ( Fmt   , [ 1 . 2 3 4 ] )w;r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : - 1 0 .e4] '; S:=  Format      ( fmt   , [ 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%-*.*      e ] ';S :=  Format      ( fmt  , [ 4 , 5 , 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
   e x c e p t
      On    E  :   E x c e p t i o ndo
          b e g i n
          W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
          end   ;
   end   ;
   w r i t e l n ( ' P r e s s|_|e n t e'r) ;
   r e a d l n;
end  ;


Procedure        T e s t N e g a t i v e E x p o n e n t i;a l


b e g i n
   Try
       Fmt  := '[%   e ] ';S :=  Format      ( Fmt  , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%10    e ] '; S := Format      ( Fmt   , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 1 0 . 4e] ';S :=  Format      ( Fmt  , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 :e] '; S := Format      ( Fmt   , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : 1 0e] ';S :=  Format      ( Fmt  , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt   : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : 1 0 .e4] '; S := Format      ( Fmt   , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%0:-10      e ] ' ;S := Format      ( Fmt   , [ - 1 . 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  :=  ' [ % 0 : - 1 0 .e4] '; S:=  Format      ( fmt  , [ - 1 . 2 3 4 ] ) ;w r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
       Fmt  := '[%-*.*      e ] ';S :=  Format      ( fmt  , [ 4 , 5 , - 1 . 2 3 4 ] )w;r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
   e x c e p t
      On    E  :   E x c e p t i o ndo
          b e g i n
          W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
          end   ;
   end   ;
   w r i t e l n ( ' P r e s s|_|e n t e'r) ;
   r e a d l n;
end  ;


                                                                429

 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________________________*
 *____
 Procedure        T e s t S m a l l E x p o n e n t i;a l


 b e g i n
    Try
        Fmt  := '[%   e ] ';S :=  Format      ( Fmt  , [ 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  := '[%10    e ] '; S := Format      ( Fmt   , [ 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 1 0 . 4e] ';S :=  Format      ( Fmt  , [ 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 :e] '; S := Format      ( Fmt   , [ 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 : 1 0e] ';S :=  Format      ( Fmt  , [ 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 : 1 0 .e4] '; S := Format      ( Fmt   , [ 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  := '[%0:-10      e ] ' ;S := Format      ( Fmt   , [ 0 . 0 1 2 3 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 : - 1 0 .e4] '; S:=  Format      ( fmt   , [ 0 . 0 1 2 3 4 ] )w;r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
        Fmt  := '[%-*.*      e ] ';S :=  Format      ( fmt  , [ 4 , 5 , 0 . 0 1 2 3 4 ] )w;r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s) ;
    e x c e p t
       On    E  :   E x c e p t i o ndo
           b e g i n
           W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
           end   ;
    end   ;
    w r i t e l n ( ' P r e s s|_|e n t e'r) ;
    r e a d l n;
 end  ;


 Procedure        T e s t S m a l l N e g E x p o n e n t i;a l


 b e g i n
    Try
        Fmt  := '[%   e ] ';S :=  Format      ( Fmt  , [ - 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  := '[%10    e ] '; S := Format      ( Fmt   , [ - 0 . 0 1 2 3 4 ] )w;r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 1 0 . 4e] ';S :=  Format      ( Fmt  , [ - 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 :e] '; S := Format      ( Fmt   , [ - 0 . 0 1 2 3 4 ] )w;r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 : 1 0e] ';S :=  Format      ( Fmt  , [ - 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 : 1 0 .e4] '; S := Format      ( Fmt   , [ - 0 . 0 1 2 3 4 ] )w;r i t e l(nFmt   : 1 2 ,' |_|=> |_|',s) ;
        Fmt  := '[%0:-10      e ] ' ;S := Format      ( Fmt   , [ - 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  :=  ' [ % 0 : - 1 0 .e4] '; S:=  Format      ( fmt  , [ - 0 . 0 1 2 3 4 ] )w;r i t e l n(Fmt  : 1 2 ,' |_|=> |_|',s) ;
        Fmt  := '[%-*.*      e ] ';S :=  Format      ( fmt  , [ 4 , 5 , - 0 . 0 1 2 3 4 ] )w;r i t e l(nFmt  : 1 2 ,' |_|=> |_|',s)*
 * ;
    e x c e p t
       On    E  :   E x c e p t i o ndo
           b e g i n
           W r i t e l n ( ' E x c e p t i o|n_|c a u g h|t_|: |_|',E.Message    ) ;
           end   ;
    end   ;
    w r i t e l n ( ' P r e s s|_|e n t e'r) ;
    r e a d l n;
 end  ;


 b e g i n
    T e s t I n t e g e;r
    T e s t H e x a d e c i m a;l
    T e s t P o i n t e;r
    T e s t E x p o n e n t i a;l
    T e s t N e g a t i v e E x p o n e n t i;a l
    T e s t S m a l l E x p o n e n t i;a l
    T e s t S m a l l N e g E x p o n e n t i;a l
_end__._________________________________________________________________________________________________________________________

                                                                 430

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.28         FormatBuf

Declaration:      Function  FormatBuf(Var  Buffer;  BufLen  :    Cardinal;  Const  Fmt;  fmtLen  :    Cardinal;
                 Const  Args  :    Array  of  const)  :    Cardinal;

Description:      Format

       Errors:

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example72      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  FormatBuf        f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var
                    S   :  S h o r t S t r i n;g


                 Const
                    Fmt    :   S h o r t S t r i n g=    ' For  |_|some  |_|n i c|e_|e x a m p l e|s_|o|f_|f o m a t t i|n_g|s|e_e|*
 *%s. ';


                 Begin
                    S :=  ' ';
                    S e t L e n g t h(S, FormatBuf        ( S [ 1 ] , 2 5 5 ,Fmt  [ 1 ] ,Length    (Fmt   ) , [' Format    ' ] ) ) ;
                    W r i t e l n ( S ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.29         IntToHex

Declaration:      Function  IntToHex(Value:    integer;  Digits:    integer):    string;

Description:      IntToHex converts Value to a hexadecimal string representation.  The result will contain at
                 least Digits characters.  If  Digits is less than the needed number of characters, the string
                 will NOT be truncated.  If Digits is larger than the needed number of characters, the result
                 is padded with zeroes.

       Errors:    None.

     See also:    IntToStr (432), StrToInt


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example73      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  IntToHex       f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    I  :   l o n g i n t;


                 Begin
                    For    I :=0    to   3 1  do
                           b e g i n
                           W r i t e l n ( IntToHex      ( 1  s h l  I , 8 ) ) ;
                           W r i t e l n ( IntToHex      ( 1 5  s h l  I , 8 ) )
                           end   ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 431

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.30         IntToStr

Declaration:      Function  IntToStr(Value:    integer):    string;

Description:      IntToStr coverts Value to it's string representation.  The resulting string has only as much
                 characters as needed to represent the value.  If the value is negative a minus sign is prepended
                 to the string.

       Errors:    None.

     See also:    IntToHex (431), StrToInt (436)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example74      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  I n t T o S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    I  :   l o n g i n t;


                 Begin
                    For    I :=0    to   3 1  do
                           b e g i n
                           W r i t e l n ( I n t T o S t r( 1 s h l  I ) ) ;
                           W r i t e l n ( I n t T o S t r( 1 5 s h l  I ) ) ;
                           end   ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.31         IsValidIdent

Declaration:      Function  IsValidIdent(const  Ident:    string):    boolean;

Description:      IsValidIdent returns True if  Ident can be used as a compoent name.  It returns False
                 otherwise.  Ident must consist of a letter or underscore, followed by a combination of letters,
                 numbers or underscores to be a valid identifier.

       Errors:    None.

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example75      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  I s V a l i d I d e n tf u n c t i o n}


                 Uses     s y s u t i l;s


                 Procedure        T e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                    Write     (  ' " ',S , ' " |_|i s|_|') ;
                    I f  not     I s V A l i d I d e n(tS)  then
                        Write   ( ' NOT  |_|') ;
                    W r i t e l n ( ' a |_|v a l i|d_|i d e n t i f i'e)r;
                 end  ;


                 Begin
                                                                                 432

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                    T e s t i t ( ' __MyObj   ' ) ;
                    T e s t i t ( ' My__ __Obj1   ' ) ;
                    T e s t i t ( ' My__1__Obj    ' ) ;
                    T e s t i t ( ' 1 MyObject      ' ) ;
                    T e s t i t ( ' My@Object       ' ) ;
                    T e s t i t ( ' M123   ' ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.32         LeftStr

Declaration:      Function  LeftStr(const  S:  string;  Count:    integer):    string;

Description:      LeftStr returns the Count leftmost characters of S. It is equivalent to a call to Copy(S,1,Count).

       Errors:    None.

     See also:    RightStr (435), TrimLeft (438), TrimRight (438), Trim (437)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example76      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  L e f t S t r f u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y2z0 ) ) ;
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y1z5 ) ) ;
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y1z) ) ;
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y2z0 0 ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.33         LoadStr

Declaration:      Function  LoadStr(Ident:    integer):    string;

Description:      This function is not yet implemented.  resources are not yet supported.

       Errors:

     See also:
                 20.8.34         LowerCase

Declaration:      Function  LowerCase(const  s:    string):    string;

Description:      LowerCase returns the lowercase equivalent of S. Ansi characters are not taken into account,
                 only  ASCII  codes  below  127  are  converted.   It  is  completely  equivalent  to  the  lowercase
                 function of the system unit, and is provided for compatiibility only.

       Errors:    None.

     See also:    AnsiLowerCase (412), UpperCase (439), AnsiUpperCase (418)

                                                                                 433

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example77      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  LowerCase        f u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( LowerCase       (' THIS   |_|WILL  |_|COME  |_|out |_|a l l|_|LoWeRcAsE    |_|! ') ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.35         NewStr

Declaration:      Function  NewStr(const  S:  string):    PString;

Description:      NewStr assigns a new dynamic string on the heap, copies S into it, and returns a pointer
                 to the newly assigned string.

                 This function is obsolete, and shouldn't be used any more.  The AnsiString mechanism also
                 allocates ansistrings on the heap, and should be preferred over this mechanism.

       Errors:    If not enough memory is present, an EOutOfMemory exception will be raised.

     See also:    AssignStr (419), DisposeStr (422)


                 For an example, see AssignStr (419).
                 20.8.36         QuotedStr

Declaration:      Function  QuotedStr(const  S:  string):    string;

Description:      QuotedStr  returns  the  string  S,  quoted  with  single  quotes.   This  means  that  S  is  en-
                 closed  in  single  quotes,  and  every  single  quote  in  S  is  doubled.   It  is  equivalent  to  a  call
                 to AnsiQuotedStr(s,  '''').

       Errors:    None.

     See also:    AnsiQuotedStr (412), AnsiExtractQuotedStr (411).


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example78      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  Q u o t e d S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   A n s i S t r i n;g


                 Begin
                    S :=  'He  |_|s a i d|_|''H e l l'o' |_|and |_|w a l k e|d_|on';
                    W r i t e l n ( S ) ;
                    W r i t e l n ( ' |_||_|becomes  ' ) ;
                    W r i t e l n ( Q u o t e d S t r(S) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                                                                                 434

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.37         RightStr

Declaration:      Function  RightStr(const  S:  string;  Count:    integer):    string;

Description:      RightStr returns the Count rightmost characters of S. It is equivalent to a call to Copy(S,Length(S)+1-Count,Coun*
 *t).

                 If  Count is larger than the actual length of  S only the real length will be used.

       Errors:    None.

     See also:    LeftStr (433),Trim (437), TrimLeft (438), TrimRight (438)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example79      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  R i g h t S t rf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( R i g h t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y2z0 ) ) ;
                    W r i t e l n ( R i g h t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y1z5 ) ) ;
                    W r i t e l n ( R i g h t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y1z) ) ;
                    W r i t e l n ( R i g h t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y2z0 0 ) ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.38         StrFmt

Declaration:      Function  StrFmt(Buffer,Fmt  :    PChar;  Const  args:    Array  of  const)  :    Pchar;

Description:      StrFmt will format fmt with Args, as the Format (425) function does, and it will store the
                 result  in  Buffer.  The  function  returns  Buffer.  Buffer  should  point  to  enough  space  to
                 contain the whole result.

       Errors:    for a list of errors, see Format (425).

     See also:    StrLFmt (435), FmtStr (425), Format (425), FormatBuf  (431)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example80      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  StrFmt      f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   A n s i S t r i n;g


                 Begin
                    S e t L E n g t h(S , 8 0 ) ;
                    W r i t e l n ( StrFmt      ( @S  [ 1 ] ,'For  |_|some  |_|n i c e|_|e x a m p l e|s_|o|f_|f o m a t t i|n_g|s|*
 *e_e|%s. ', ['Format     '] ) ) @
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.39         StrLFmt

Declaration:      Function  StrLFmt(Buffer  :    PCHar;  Maxlen  :    Cardinal;Fmt  :    PChar;  Const  args:
                 Array  of  const)  :    Pchar;


                                                                                 435

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
Description:      StrLFmt will format fmt with Args, as the Format (425) function does, and it will store max-
                 imally Maxlen  characters of the result in Buffer.  The function returns Buffer.  Buffer
                 should point to enough space to contain MaxLen characters.

       Errors:    for a list of errors, see Format (425).

     See also:    StrFmt (435), FmtStr (425), Format (425), FormatBuf  (431)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example80      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  StrFmt      f u n c t i o n}


                 Uses     s y s u t i l;s


                 Var    S  :   A n s i S t r i n;g


                 Begin
                    S e t L E n g t h(S , 8 0 ) ;
                    W r i t e l n ( StrLFmt       (@S  [ 1 ] , 8 0 ,'For  |_|some  |_|n i c e|_|e x a m p l|e_s|o|f_|f o m a t t i|*
 *n_g|s e|e_|%s. ', ['Format    '@
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.40         StrToInt

Declaration:      Function  StrToInt(const  s:    string):    integer;

Description:      StrToInt will convert the string Sto an integer.  If the string contains invalid characters or
                 has an invalid format, then an EConvertError is raised.

                 To be successfully converted, a string can contain a combination of  numerical characters,
                 possibly preceded by a minus sign (-).  Spaces are not allowed.

       Errors:    In case of error, an EConvertError is raised.

     See also:    IntToStr (432), StrToIntDef  (437)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example82      ;


                 {$mode      o b j f p c}


                 {  T h i s  program       d e m o n s t r a t e st h e  S t r T o I n tf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( S t r T o I n t(' 1 2 3 4 ') ) ;
                    W r i t e l n ( S t r T o I n t(' - 1 2 3 4 ') ) ;
                    W r i t e l n ( S t r T o I n t(' 0 ') ) ;
                    Try
                        W r i t e l n( S t r T o I n t(' 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9)0)';
                    e x c e p t
                       On    E  :   E C o n v e r t E r r o rdo
                           W r i t e l n ( ' I n v a l i d|_|number  |_|e n c o u n t e r e'd) ;
                    end   ;
                _End__.____________________________________________________________________________________________________________*
 *_____________



                                                                                 436

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 20.8.41         StrToIntDef

Declaration:      Function  StrToIntDef(const  S:  string;  Default:    integer):    integer;

Description:      StrToIntDef will convert a string to an integer.  If the string contains invalid characters or
                 has an invalid format, then Default is returned.

                 To be successfully converted, a string can contain a combination of  numerical characters,
                 possibly preceded by a minus sign (-).  Spaces are not allowed.

       Errors:    None.

     See also:    IntToStr (432), StrToInt (436)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example82      ;


                 {$mode      o b j f p c}


                 {  T h i s  program       d e m o n s t r a t e st h e  S t r T o I n tf u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( S t r T o I n t D e(f' 1 2 3 4 ', 0 ) ) ;
                    W r i t e l n ( S t r T o I n t D e(f' - 1 2 3 4 ', 0 ) ) ;
                    W r i t e l n ( S t r T o I n t D e(f' 0 ', 0 ) ) ;
                    Try
                        W r i t e l n( S t r T o I n t D e f(' 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9,00') ) ;
                    e x c e p t
                       On    E  :   E C o n v e r t E r r o rdo
                           W r i t e l n ( ' I n v a l i d|_|number  |_|e n c o u n t e r e'd) ;
                    end   ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.42         Trim

Declaration:      Function  Trim(const  S:  string):    string;

Description:      Trim strips blank characters (spaces) at the beginning and end of S and returns the resulting
                 string.  Only #32 characters are stripped.

                 If the string contains only spaces, an empty string is returned.

       Errors:    None.

     See also:    TrimLeft (438), TrimRight (438)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example84      ;


                 {  T h i s  program       d e m o n s t r a t e st h e Trim     f u n c t i o n}


                 Uses     s y s u t i l;s
                 {$H  +}


                 Procedure        T e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                    W r i t e l n ( ' " ', Trim   (S  ) ,' " ') ;



                                                                                 437

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________
                 end  ;


                 Begin
                    T e s t i t ( ' |_||_|ha|_|ha|_|what |_|g e t s|_|l o s|t_|? |_|') ;
                    T e s t i t (#10#13      'haha    |_|') ;
                    T e s t i t ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_|') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.43         TrimLeft

Declaration:      Function  TrimLeft(const  S:  string):    string;

Description:      TrimLeft strips blank characters (spaces) at the beginning of  S and returns the resulting
                 string.  Only #32 characters are stripped.

                 If the string contains only spaces, an empty string is returned.

       Errors:    None.

     See also:    Trim (437), TrimRight (438)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example85      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  T r i m L e f tf u n c t i o n}


                 Uses     s y s u t i l;s
                 {$H  +}


                 Procedure        T e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                    W r i t e l n ( ' " ', T r i m L e f t(S) , ' " ') ;
                 end  ;


                 Begin
                    T e s t i t ( ' |_||_|ha|_|ha|_|what |_|g e t s|_|l o s|t_|? |_|') ;
                    T e s t i t (#10#13      'haha    |_|') ;
                    T e s t i t ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_|') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.44         TrimRight

Declaration:      Function  TrimRight(const  S:  string):    string;

Description:      Trim strips blank characters (spaces) at the end of S and returns the resulting string.  Only
                 #32 characters are stripped.

                 If the string contains only spaces, an empty string is returned.

       Errors:    None.

     See also:    Trim (437), TrimLeft (438)


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example86      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  T r i m R i g h tf u n c t i o n}



                                                                                 438

                 _________________________________________________________________________20.8.___STRING_HANDLING_FUNCTIONS________*
 *____________________


                 Uses     s y s u t i l;s
                 {$H  +}


                 Procedure        T e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                    W r i t e l n ( ' " ', T r i m R i g h t(S) , ' " ') ;
                 end  ;


                 Begin
                    T e s t i t ( ' |_||_|ha|_|ha|_|what |_|g e t s|_|l o s|t_|? |_|') ;
                    T e s t i t (#10#13      'haha    |_|') ;
                    T e s t i t ( ' |_||_||_||_||_||_||_||_||_||_||_||_||_||_|') ;
                _End__.____________________________________________________________________________________________________________*
 *_____________
                 20.8.45         UpperCase

Declaration:      Function  UpperCase(const  s:    string):    string;

Description:      UpperCase returns the uppercase equivalent of S. Ansi characters are not taken into account,
                 only ASCII codes below 127 are converted.  It is completely equivalent to the UpCase function
                 of the system unit, and is provided for compatiibility only.

       Errors:    None.

     See also:    AnsiLowerCase (412), LowerCase (433), AnsiUpperCase (418)

       Errors:

     See also:


                ___________________________________________________________________________________________________________________*
 *_____________
                 Program       Example87      ;


                 {  T h i s  program       d e m o n s t r a t e st h e  UpperCase        f u n c t i o n}


                 Uses     s y s u t i l;s


                 Begin
                    W r i t e l n ( UpperCase       (' t h i s|_|w i l l|_|come |_|OUT |_|ALL |_|uPpErCaSe     |_|! ') ) ;
                _End__.____________________________________________________________________________________________________________*
 *_____________

                                                                                 439



Index


Abstract, 284                                                       CFSetISpeed, 174
Accept, 346-348                                                     CFSetOSpeed, 174
Access, 169                                                         ChangeFileExt, 392
AddDisk, 41                                                         Chmod, 175
AddDisk (Linux only), 389                                           Chown, 174
AdjustLineBreaks, 409                                               Circle, 117
Alarm, 170                                                          ClearDevice, 117
allocate__ ldt__ descriptors, 82                                    ClearViewPort, 117
allocate__ memory__ block, 84                                       Clone, 176
AnsiCompareStr, 409                                                 CloseDir, 177
AnsiCompareText, 410                                                CloseGraph, 117
AnsiExtractQuotedStr, 411                                           ClrEol, 27
AnsiLastChar, 411                                                   ClrScr, 28
AnsiLowerCase, 412                                                  CompareMem, 420
AnsiQuotedStr, 412                                                  CompareStr, 420
AnsiStrComp, 413                                                    CompareText, 421
AnsiStrIComp, 413                                                   Connect, 349, 350
AnsiStrLastChar, 414                                                copyfromdos, 85
AnsiStrLComp, 415                                                   copytodos, 85
AnsiStrLIComp, 416                                                  cosh, 242
AnsiStrLower, 416                                                   cotan, 243
AnsiStrUpper, 417                                                   create__ code__ segment__ alias__ descriptor, 85
AnsiUpperCase, 418                                                  CreateDir, 389
AppendStr, 418                                                      CreateShellArgV, 177
Arc, 116                                                            CursorBig, 27
arccos, 239                                                         CursorOff, 28
arcosh, 239                                                         CursorOn, 28
arcsin, 240                                                         cycletorad, 243
arctan2, 240
arsinh, 241                                                         Date, 376
artanh, 241                                                         DateTimeToFileDate, 376
AssignCrt, 26                                                       DateTimeToStr, 377
AssignLst, 343                                                      DateTimeToString, 377
AssignPipe, 171                                                     DateTimeToSystemTime, 378
AssignStr, 419                                                      DateTimeToTimeStamp, 378
AssignStream, 171                                                   DateToStr, 379
                                                                    DayOfWeek, 379
Bar, 116                                                            DecodeDate, 380
Bar3D, 116                                                          DecodeTime, 380
BaseName, 173                                                       degtograd, 244
BCDToInt, 419                                                       degtorad, 244
Bind, 348, 349                                                      Delay, 28
                                                                    DeleteFile, 392
ceil, 242                                                           DelLine, 29
CFMakeRaw, 173                                                      DetectGraph, 117
                                                            440

__________________________________________________________________________________________________________________________INDEX____*
 *___
DirName, 178                                                        fdWrite, 190
disable, 86                                                         FExpand, 45, 190
DiskFree, 42, 390                                                   FileAge, 396
DiskSize, 42, 390                                                   FileClose, 397
DisposeStr, 284, 422                                                FileCreate, 397
DoDirSeparators, 393                                                FileDateToDateTime, 382
DosExitCode, 43                                                     FileExists, 398
dosmemfillchar, 86                                                  FileGetAttr, 398
dosmemfillword, 87                                                  FileGetDate, 400
dosmemget, 87                                                       FileOpen, 400
dosmemmove, 87                                                      FileRead, 401
dosmemput, 88                                                       FileSearch, 401
DosVersion, 43                                                      FileSeek, 401
DrawPoly, 118                                                       FileSetAttr (Not on Linux), 402
DumpHeap, 136                                                       FileSetDate (Not on Linux), 402
Dup, 179                                                            FileTruncate, 403
Dup2, 179                                                           FileWrite, 403
dxe__ load, 57                                                      FillEllipse, 118
                                                                    FillPoly, 118
Ellipse, 118                                                        FindClose, 45, 403
Emms, 269                                                           FindFirst, 46, 403
enable, 88                                                          FindNext, 47, 404
EncodeDate, 381                                                     FloatToStr, 422
EncodeTime, 381                                                     FloatToStrF, 423
EnvCount, 44                                                        FloatToText, 424
EnvStr, 44                                                          FLock, 190
EpochToLocal, 180                                                   FloodFill, 118
Exec, 45                                                            floor, 245
Execl, 181                                                          FmtStr, 425
Execle, 181                                                         FNMatch, 191
Execlp, 182                                                         Fork, 195
Execv, 183                                                          Format, 425
Execve, 184                                                         FormatBuf, 431
Execvp, 185                                                         FormatDateTime, 382
ExpandFileName, 393                                                 free__ ldt__ descriptor, 88
ExpandUNCFileName, 394                                              free__ memory__ block, 89
ExtractFileDir, 394                                                 free__ rm__ callback, 89
ExtractFileDrive, 395                                               FRename, 195
ExtractFileExt, 395                                                 frexp, 245
ExtractFileName, 395                                                FSearch, 47, 191
ExtractFilePath, 396                                                FSplit, 47, 192
ExtractRelativePath, 396                                            FSStat, 192

                                                                    FStat, 193
Fcntl, 194, 195                                                     ftok, 144
FD__ Clr, 186
FD__ IsSet, 186                                                     get__ cs, 89
FD__ Set, 186                                                       get__ descriptor__ access__ rights, 90
FD__ ZERO, 185                                                      get__ ds, 90
fdClose, 186                                                        get__ linear__ addr, 90
fdFlush, 187                                                        get__ meminfo, 90
fdOpen, 187                                                         get__ next__ selector__ increment__ value, 91
fdRead, 188                                                         get__ page__ size, 92
fdSeek, 189                                                         get__ pm__ interrupt, 92
fdTruncate, 189                                                     get__ rm__ callback, 92



                                                                441

__________________________________________________________________________________________________________________________INDEX____*
 *___
get__ rm__ interrupt, 95                                            GetSocketOptions, 352
get__ run__ mode, 95                                                GetTextSettings, 122
get__ segment__ base__ address, 96                                  GetTime, 51, 202
get__ segment__ limit, 96                                           GetTimeOfDay, 203
get__ ss, 97                                                        GetTimezoneFile, 203
GetArcCoords, 119                                                   GetUid, 203
GetAspectRatio, 119                                                 GetVerify, 52
GetBkColor, 119                                                     GetViewSettings, 122
GetCBreak, 48                                                       GetX, 122
GetColor, 119                                                       GetY, 122
GetCurrentDir, 391                                                  Glob, 204
GetDate, 48, 196                                                    global__ dos__ alloc, 97
GetDateTime, 197                                                    global__ dos__ free, 98
GetDefaultPalette, 119                                              GlobFree, 204
GetDirs, 404                                                        GotoXY, 29
GetDomainName, 197                                                  Gpm__ AnyDouble, 66
GetDriverName, 119                                                  Gpm__ AnySingle, 66
GetEGid, 197                                                        Gpm__ AnyTriple, 67
GetEnv, 49, 198                                                     Gpm__ Close, 67
GetEpochTime, 199                                                   Gpm__ FitValues, 67
GetEUid, 198                                                        Gpm__ FitValuesM, 67
GetFAttr, 49                                                        Gpm__ GetEvent, 68
GetFillPattern, 120                                                 Gpm__ GetLibVersion, 69
GetFillSettings, 120                                                Gpm__ GetServerVersion, 69
GetFS, 199                                                          Gpm__ GetSnapshot, 69
GetFTime, 50                                                        Gpm__ LowerRoi, 70
GetGid, 200                                                         Gpm__ Open, 70
GetGraphMode, 120                                                   Gpm__ PopRoi, 70
GetHostName, 200                                                    Gpm__ PushRoi, 70
GetImage, 120                                                       Gpm__ RaiseRoi, 71
GetIntVec, 51                                                       Gpm__ Repeat, 71
GetLastButtonPress, 271                                             Gpm__ StrictDouble, 71
GetLastButtonRelease, 272                                           Gpm__ StrictSingle, 71
GetLineSettings, 120                                                Gpm__ StrictTriple, 72
GetLocalTimezone, 201                                               gradtodeg, 246
GetLongName, 51                                                     gradtorad, 246
GetLongOpts, 61                                                     GraphDefaults, 123
GetMaxColor, 120                                                    GraphErrorMsg, 123
GetMaxMode, 121                                                     GraphResult, 123
GetMaxX, 121
GetMaxY, 121                                                        HideMouse, 274
GetModeName, 121                                                    HighVideo, 30
GetModeRange, 121                                                   hypot, 247
GetMouseState, 272
Getopt, 61                                                          ImageSize, 123
GetPalette, 121                                                     IncMonth, 383
GetPaletteSize, 122                                                 InitGraph, 124
GetPeerName, 351                                                    InitMouse, 274
GetPid, 201                                                         inportb, 99
GetPixel, 122                                                       inportl, 99
GetPPid, 201                                                        inportw, 99
GetPriority, 202                                                    InsLine, 30
GetShortName, 51                                                    InstallUserDriver, 124
GetSocketName, 351                                                  InstallUserFont, 124



                                                                442

__________________________________________________________________________________________________________________________INDEX____*
 *___
intpower, 247                                                       msgctl, 145
Intr, 52                                                            msgget, 144
IntToHex, 431                                                       msgrcv, 145
IntToStr, 432                                                       msgsnd, 144
IOCtl, 205                                                          MUnMap, 213
IOperm, 205
IsATTY, 206                                                         NewStr, 283, 434
IsLeapYear, 383                                                     Nice, 213
IsValidIdent, 432                                                   norm, 256
                                                                    NormVideo, 32
Keep, 52                                                            NoSound, 32
KeyPressed, 31                                                      Now, 384
Kill, 208                                                           npxsetup, 59


ldexp, 248                                                          Octal, 214
LeftStr, 433                                                        OpenDir, 214
Line, 125                                                           outportb, 100
LineRel, 125                                                        outportl, 101
LineTo, 125                                                         outportw, 101
Link, 209                                                           OutText, 126
Listen, 352                                                         OutTextXY, 126
lnxp1, 248
LoadStr, 433                                                        PackTime, 53
LocalToEpoch, 210                                                   pause, 215
lock__ code, 99                                                     PClose, 215
lock__ data, 100                                                    PieSlice, 126
lock__ linear__ region, 100                                         POpen, 216
log10, 249                                                          popnstddev, 257
log2, 249                                                           popnvariance, 258
logn, 250                                                           power, 258
LongDiv, 286                                                        PutImage, 126
LongMul, 286                                                        PutPixel, 127
LowerCase, 433
LowVideo, 31                                                        QuotedStr, 434
LPressed, 275                                                       radtocycle, 259
LStat, 208                                                          radtodeg, 259


MarkHeap, 136                                                       radtograd, 260
max, 250                                                            randg, 260
maxIntValue, 251                                                    ReadDir, 217
maxvalue, 251                                                       ReadKey, 33
mean, 252                                                           ReadLink, 217
meanandstddev, 253                                                  ReadPort, 218
min, 254                                                            ReadPortB, 218
minIntValue, 254                                                    ReadPortL, 218
minvalue, 255                                                       ReadPortW, 219
MkFifo, 211                                                         ReadTimezoneFile, 219
MMap, 211                                                           realintr, 101
momentskewkurtosis, 256                                             Rectangle, 127
MoveRel, 125                                                        Recv, 353
MoveTo, 125                                                         RegisterBGIDriver, 127
MPressed, 275                                                       RegisterBGIFont, 127
MSDos, 53                                                           RegisterObjects, 284
MSecsToTimeStamp, 384                                               RegisterType,R284emoveDir, 391
                                                                443

__________________________________________________________________________________________________________________________INDEX____*
 *___
RenameFile, 405                                                     SetMouseXRange, 279
RestoreCRTMode, 127                                                 SetMouseYRange, 280
RightStr, 435                                                       SetPalette, 130
RPressed, 275                                                       SetPriority, 221
                                                                    SetRGBPalette, 130
S__ ISBLK, 206                                                      SetSocketOptions, 354
S__ ISCHR, 206                                                      SetTextJustify, 131
S__ ISDIR, 206                                                      SetTextStyle, 131
S__ ISFIFO, 206                                                     SetTime, 55
S__ ISLNK, 207                                                      SetUserCharSize, 131
S__ ISREG, 207                                                      SetVerify, 55
S__ ISSOCK, 207                                                     SetViewPort, 132
Sector, 128                                                         SetVisualPage, 132
SeekDir, 219                                                        SetWriteMode, 132
seg__ fillchar, 102                                                 Shell, 221
seg__ fillword, 103                                                 shmat, 154
seg__ move, 103                                                     shmctl, 154
segment__ to__ descriptor, 103                                      shmdt, 154
Select, 220                                                         shmget, 153
SelectText, 221                                                     ShowMouse, 280
semctl, 149                                                         Shutdown, 354
semget, 148                                                         SigAction, 222
semop, 148                                                          Signal, 225
Send, 353                                                           SigPending, 223
set__ descriptor__ access__ rights, 104                             SigProcMask, 223
set__ pm__ interrupt, 104                                           SigRaise, 224
set__ rm__ interrupt, 105                                           SigSuspend, 224
set__ segment__ base__ address, 105                                 sincos, 261
set__ segment__ limit, 106                                          sinh, 262
SetActivePage, 128                                                  Sock2File, 354
SetAllPallette, 128                                                 Sock2Text, 355
SetAspectRatio, 128                                                 Socket, 355
SetBkColor, 128                                                     SocketPair, 355
SetCBreak, 54                                                       Sound, 33
SetColor, 129                                                       stddev, 262
SetCurrentDir, 391                                                  Str2UnixSockAddr, 355
SetDate, 54                                                         StrAlloc, 357, 407
SetDirSeparators, 406                                               StrBufSize, 407
SetExtraInfo, 137                                                   StrCat, 357
SetFAttr, 54                                                        StrComp, 358
SetFillPattern, 129                                                 StrCopy, 358
SetFillStyle, 129                                                   StrDispose, 359, 408
SetFTime, 55                                                        StrECopy, 359
SetGraphBufSize, 129                                                StrEnd, 360
SetGraphMode, 130                                                   StrFmt, 435
SetHeapTraceOutput, 138                                             StrIComp, 360
SetIntVec, 55                                                       StringToPPchar, 225
SetLineStyle, 130                                                   StrLCat, 361
SetMouseAscii, 275                                                  StrLComp, 361
SetMouseHideWindow, 276                                             StrLCopy, 362
SetMousePos, 276                                                    StrLen, 362
SetMouseShape, 277                                                  StrLFmt, 435
SetMouseSpeed, 278                                                  StrLIComp, 363
SetMouseWindow, 279                                                 StrLower, 363



                                                                444

__________________________________________________________________________________________________________________________INDEX____*
 *___
StrMove, 363                                                        TCollection.IndexOf, 313
StrNew, 364                                                         TCollection.Init, 311
StrPas, 364, 408                                                    TCollection.Insert, 318
StrPCopy, 365, 408                                                  TCollection.LastThat, 314
StrPLCopy, 408                                                      TCollection.Load, 311
StrPos, 365                                                         TCollection.Pack, 315
StrRScan, 366                                                       TCollection.PutItem, 324
StrScan, 366                                                        TCollection.SetLimit, 322
StrToDate, 385                                                      TCollection.Store, 323
StrToDateTime, 385                                                  TCSendBreak, 230
StrToInt, 436                                                       TCSetAttr, 230
StrToIntDef, 437                                                    TCSetPGrp, 231
StrToTime, 386                                                      TDateTime, 376
StrUpper, 367                                                       TDosStream.Close, 301
sum, 263                                                            TDosStream.Done, 301
sumofsquares, 263                                                   TDosStream.Init, 301
sumsandsquares, 264                                                 TDosStream.Open, 303
SwapVectors, 55                                                     TDosStream.Read, 304
SymLink, 226                                                        TDosStream.Seek, 302
SysInfo, 227                                                        TDosStream.Truncate, 302
SystemTimeToDateTime, 387                                           TDosStream.Write, 304
                                                                    TellDir, 231
tan, 265                                                            TextBackground, 33
tanh, 265                                                           TextColor, 34
tb__ size, 106                                                      TextHeight, 132
TBufStream.Close, 306                                               TextMode, 34
TBufStream.Done, 305                                                TextWidth, 132
TBufStream.Flush, 306                                               Time, 387
TBufStream.Init, 305                                                TimeStampToDateTime, 387
TBufStream.Open, 307                                                TimeStampToMSecs, 388
TBufStream.Read, 307                                                TimeToStr, 388
TBufStream.Seek, 307                                                TMemoryStream.Done, 309
TBufStream.Truncate, 307                                            TMemoryStream.Init, 308
TBufStream.Write, 308                                               TMemoryStream.Read, 309
TCDrain, 228                                                        TMemoryStream.Truncate, 309
TCFlow, 229                                                         TMemoryStream.Write, 310
TCFlush, 229                                                        TObject.Done, 292
TCGetAttr, 229                                                      TObject.Free, 292
TCGetPGrp, 230                                                      TObject.Init, 291
TCollection.At, 312                                                 totalvariance, 266
TCollection.AtDelete, 320                                           transfer__ buffer, 106
TCollection.AtFree, 319                                             TRect.Assign, 291
TCollection.AtInsert, 323                                           TRect.Contains, 288
TCollection.AtPut, 322                                              TRect.Copy, 288
TCollection.Delete, 319                                             TRect.Empty, 287
TCollection.DeleteAll, 317                                          TRect.Equals, 287
TCollection.Done, 312                                               TRect.Grow, 290
TCollection.Error, 322                                              TRect.Intersect, 289
TCollection.FirstThat, 315                                          TRect.Move, 290
TCollection.ForEach, 321                                            TRect.Union, 288
TCollection.Free, 318                                               TResourceCollection.FreeItem, 335
TCollection.FreeAll, 316                                            TResourceCollection.GetItem, 334
TCollection.FreeItem, 320                                           TResourceCollection.KeyOf, 334
TCollection.GetItem, 314                                            TResourceCollection.PutItem, 335



                                                                445

__________________________________________________________________________________________________________________________INDEX____*
 *___
TResourceFile.Count, 336                                            TUnSortedStrCollection.Insert, 333
TResourceFile.Delete, 337
TResourceFile.Done, 336                                             Umask, 232
TResourceFile.Flush, 337                                            Uname, 232
TResourceFile.Get, 336                                              UnLink, 232
TResourceFile.Init, 336                                             unlock__ code, 106
TResourceFile.KeyAt, 336                                            unlock__ data, 107
TResourceFile.Put, 337                                              unlock__ linear__ region, 107
TResourceFile.SwitchTo, 337                                         UnPackTime, 56
Trim, 437                                                           UpperCase, 439
TrimLeft, 438                                                       Utime, 233
TrimRight, 438
TSortedCollection.Compare, 326                                      variance, 266
TSortedCollection.IndexOf, 326
TSortedCollection.Init, 325                                         WaitPid, 233
TSortedCollection.Insert, 328                                       WhereX, 35
TSortedCollection.KeyOf, 325                                        WhereY, 35
TSortedCollection.Load, 325                                         Window, 35
TSortedCollection.Search, 327                                       WritePort, 234
TSortedCollection.Store, 329                                        WritePortB, 234
TStrCollection.Compare, 331                                         WritePortL, 235
TStrCollection.FreeItem, 332                                        WritePortW, 235
TStrCollection.GetItem, 331
TStrCollection.PutItem, 332
TStream.Close, 296
TStream.CopyFrom, 299
TStream.Error, 298
TStream.Flush, 297
TStream.Get, 293
TStream.GetPos, 295
TStream.GetSize, 295
TStream.Open, 296
TStream.Put, 297
TStream.Read, 299
TStream.ReadStr, 296
TStream.Reset, 297
TStream.Seek, 298
TStream.StrRead, 294
TStream.StrWrite, 298
TStream.Truncate, 297
TStream.Write, 299
TStream.WriteStr, 298
TStringCollection.Compare, 330
TStringCollection.FreeItem, 330
TStringCollection.GetItem, 329
TStringCollection.PutItem, 331
TStringList.Done, 338
TStringList.Get, 338
TStringList.Load, 338
TStrListMaker.Done, 339
TStrListMaker.Init, 339
TStrListMaker.Put, 339
TStrListMaker.Store, 340
TTYName, 231



                                                                446
