
Run-Time  Library  (RTL)  :

Reference  guide.

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

                                                                                   Free Pascal version 2.2.2:

                                                                          Reference guide for RTL units.

                                                                                         Document version 2.1

                                                                                                            June 2008


Micha"el Van Canneyt
______________________________________________________________________________________________________________________________



Contents



     0.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    93


1    Reference for unit 'BaseUnix'                                                                                        94

     1.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    94

     1.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    94

     1.3    Constants, types and variables               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    94

            1.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    94

            1.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  116

     1.4    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  131

            1.4.1     CreateShellArgV           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  131

            1.4.2     FpAccess        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  132

            1.4.3     FpAlarm         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  133

            1.4.4     FpChdir      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  133

            1.4.5     FpChmod         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  134

            1.4.6     FpChown         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  135

            1.4.7     FpClose      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  136

            1.4.8     FpClosedir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  136

            1.4.9     FpDup      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  137

            1.4.10    FpDup2       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  137

            1.4.11    FpExecv      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  138

            1.4.12    FpExecve        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  139

            1.4.13    FpExit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  140

            1.4.14    FpFcntl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  141

            1.4.15    fpfdfillset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  141

            1.4.16    fpFD_CLR          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  141

            1.4.17    fpFD_ISSET           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  142

            1.4.18    fpFD_SET        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  142

            1.4.19    fpFD_ZERO         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  142

            1.4.20    FpFork       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  142

            1.4.21    FPFStat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  143

            1.4.22    FpFtruncate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

                                                              1

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           1.4.23    FpGetcwd        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

           1.4.24    FpGetegid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

           1.4.25    FpGetEnv        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  145

           1.4.26    fpgeterrno      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  145

           1.4.27    FpGeteuid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  146

           1.4.28    FpGetgid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  146

           1.4.29    FpGetgroups          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  147

           1.4.30    FpGetpgrp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  147

           1.4.31    FpGetpid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  147

           1.4.32    FpGetppid          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148

           1.4.33    fpGetPriority        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  148

           1.4.34    FpGetuid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148

           1.4.35    FpIOCtl       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  149

           1.4.36    FpKill     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  150

           1.4.37    FpLink        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  150

           1.4.38    FpLseek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  151

           1.4.39    fpLstat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  152

           1.4.40    FpMkdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  153

           1.4.41    FpMkfifo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  153

           1.4.42    Fpmmap          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  154

           1.4.43    Fpmunmap           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  155

           1.4.44    FpNanoSleep          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  156

           1.4.45    fpNice     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  156

           1.4.46    FpOpen        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  157

           1.4.47    FpOpendir          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  158

           1.4.48    FpPause       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  159

           1.4.49    FpPipe        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  160

           1.4.50    FppRead         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  161

           1.4.51    FppWrite        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  161

           1.4.52    FpRead        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  161

           1.4.53    FpReaddir          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  162

           1.4.54    fpReadLink         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  163

           1.4.55    FpReadV         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  164

           1.4.56    FpRename           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  164

           1.4.57    FpRmdir         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  165

           1.4.58    fpSelect      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  165

           1.4.59    fpseterrno      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  167

           1.4.60    FpSetgid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  167

           1.4.61    fpSetPriority        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  167

           1.4.62    FpSetsid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  168



                                                                  2

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           1.4.63    fpsettimeofday         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  168

           1.4.64    FpSetuid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  168

           1.4.65    FPSigaction        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  169

           1.4.66    FpSigAddSet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  170

           1.4.67    FpSigDelSet        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  170

           1.4.68    FpsigEmptySet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  170

           1.4.69    FpSigFillSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  171

           1.4.70    FpSigIsMember          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  171

           1.4.71    FpSignal      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  171

           1.4.72    FpSigPending         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  172

           1.4.73    FpSigProcMask          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  172

           1.4.74    FpSigSuspend         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  173

           1.4.75    FpSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  173

           1.4.76    FpStat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  173

           1.4.77    fpSymlink       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  174

           1.4.78    fpS_ISBLK          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

           1.4.79    fpS_ISCHR          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

           1.4.80    fpS_ISDIR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

           1.4.81    fpS_ISFIFO         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

           1.4.82    fpS_ISLNK          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  177

           1.4.83    fpS_ISREG          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  177

           1.4.84    fpS_ISSOCK           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  178

           1.4.85    fptime     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  178

           1.4.86    FpTimes       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  178

           1.4.87    FpUmask         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  179

           1.4.88    FpUname         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  179

           1.4.89    FpUnlink        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  179

           1.4.90    FpUtime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  180

           1.4.91    FpWait        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  181

           1.4.92    FpWaitPid          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  181

           1.4.93    FpWrite       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  182

           1.4.94    FpWriteV        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  182

           1.4.95    FreeShellArgV          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  183

           1.4.96    wexitStatus        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  183

           1.4.97    wifexited       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  183

           1.4.98    wifsignaled        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  183

           1.4.99    wstopsig      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  184

           1.4.100   wtermsig        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  184


2    Reference for unit 'Classes'                                                                                       185
                                                                  3

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    2.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  185

    2.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  185

    2.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  185

           2.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  185

           2.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  188

           2.3.3     Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  198

    2.4    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  199

           2.4.1     ActivateClassGroup             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  199

           2.4.2     BeginGlobalLoading             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  200

           2.4.3     BinToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  200

           2.4.4     Bounds        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  200

           2.4.5     CheckSynchronize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  201

           2.4.6     ClassGroupOf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  201

           2.4.7     CollectionsEqual          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  201

           2.4.8     EndGlobalLoading            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  201

           2.4.9     ExtractStrings         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  202

           2.4.10    FindClass       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  202

           2.4.11    FindGlobalComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  202

           2.4.12    FindIdentToInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  202

           2.4.13    FindIntToIdent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  203

           2.4.14    FindNestedComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  203

           2.4.15    GetClass        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  203

           2.4.16    GetFixupInstanceNames               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  204

           2.4.17    GetFixupReferenceNames                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  204

           2.4.18    GlobalFixupReferences            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  204

           2.4.19    GroupDescendentsWith                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  204

           2.4.20    HexToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  205

           2.4.21    IdentToInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  205

           2.4.22    InitComponentRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  205

           2.4.23    InitInheritedComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  206

           2.4.24    IntToIdent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  206

           2.4.25    InvalidPoint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  206

           2.4.26    LineStart       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  206

           2.4.27    NotifyGlobalLoading            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  207

           2.4.28    ObjectBinaryToText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  207

           2.4.29    ObjectResourceToText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  207

           2.4.30    ObjectTextToBinary             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  207

           2.4.31    ObjectTextToResource             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  207

           2.4.32    Point      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  208

           2.4.33    PointsEqual        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  208



                                                                  4

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.4.34    ReadComponentRes               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  208

           2.4.35    ReadComponentResEx               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  208

           2.4.36    ReadComponentResFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  208

           2.4.37    Rect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  209

           2.4.38    RedirectFixupReferences             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  209

           2.4.39    RegisterClass        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  209

           2.4.40    RegisterClassAlias          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  210

           2.4.41    RegisterClasses        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  210

           2.4.42    RegisterComponents             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  210

           2.4.43    RegisterFindGlobalComponentProc                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *210

           2.4.44    RegisterInitComponentHandler                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 211

           2.4.45    RegisterIntegerConsts            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  211

           2.4.46    RegisterNoIcon         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  211

           2.4.47    RegisterNonActiveX             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  212

           2.4.48    RemoveFixupReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  212

           2.4.49    RemoveFixups           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  212

           2.4.50    SmallPoint         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  212

           2.4.51    StartClassGroup           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  213

           2.4.52    UnRegisterClass           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  213

           2.4.53    UnRegisterClasses           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  213

           2.4.54    UnregisterFindGlobalComponentProc                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *13

           2.4.55    UnRegisterModuleClasses               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  214

           2.4.56    WriteComponentResFile               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  214

    2.5    EBitsError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  214

           2.5.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

    2.6    EClassNotFound            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

           2.6.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

    2.7    EComponentError              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

           2.7.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

    2.8    EFCreateError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  215

           2.8.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

    2.9    EFilerError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  215

           2.9.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

    2.10   EFOpenError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  215

           2.10.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

    2.11   EInvalidImage        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  215

           2.11.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

    2.12   EInvalidOperation            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

           2.12.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

    2.13   EListError      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  215



                                                                  5

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.13.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

    2.14   EMethodNotFound              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

           2.14.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

    2.15   EOutOfResources           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

           2.15.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

    2.16   EParserError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  216

           2.16.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

    2.17   EReadError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  216

           2.17.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

    2.18   EResNotFound            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  216

           2.18.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

    2.19   EStreamError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  216

           2.19.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

    2.20   EStringListError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

           2.20.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

    2.21   EThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  217

           2.21.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

    2.22   EThreadDestroyCalled             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  217

           2.22.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

    2.23   EWriteError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  217

           2.23.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

    2.24   IDesignerNotify         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  218

           2.24.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  218

           2.24.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  218

           2.24.3    IDesignerNotify.Modified              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  218

           2.24.4    IDesignerNotify.Notification             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  218

    2.25   IInterfaceComponentReference                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  218

           2.25.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  218

           2.25.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  218

           2.25.3    IInterfaceComponentReference.GetComponent                          .  .  .  .  .  .  .  .  .  .  .  .  .  219

    2.26   IInterfaceList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  219

           2.26.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  219

           2.26.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  219

           2.26.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  219

           2.26.4    IInterfaceList.Get          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  220

           2.26.5    IInterfaceList.GetCapacity               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  220

           2.26.6    IInterfaceList.GetCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  220

           2.26.7    IInterfaceList.Put          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  220

           2.26.8    IInterfaceList.SetCapacity            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  221

           2.26.9    IInterfaceList.SetCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221



                                                                  6

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.26.10   IInterfaceList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  221

           2.26.11   IInterfaceList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  221

           2.26.12   IInterfaceList.Exchange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  222

           2.26.13   IInterfaceList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

           2.26.14   IInterfaceList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  222

           2.26.15   IInterfaceList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

           2.26.16   IInterfaceList.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

           2.26.17   IInterfaceList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  223

           2.26.18   IInterfaceList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  223

           2.26.19   IInterfaceList.Lock         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  223

           2.26.20   IInterfaceList.Unlock          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  223

           2.26.21   IInterfaceList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  223

           2.26.22   IInterfaceList.Count           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  224

           2.26.23   IInterfaceList.Items           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  224

    2.27   IStreamPersist          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  224

           2.27.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  224

           2.27.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  224

           2.27.3    IStreamPersist.LoadFromStream                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 225

           2.27.4    IStreamPersist.SaveToStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  225

    2.28   IStringsAdapter         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  225

           2.28.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  225

           2.28.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  225

           2.28.3    IStringsAdapter.ReferenceStrings                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 225

           2.28.4    IStringsAdapter.ReleaseStrings               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 225

    2.29   TAbstractObjectReader               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  226

           2.29.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  226

           2.29.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  226

           2.29.3    TAbstractObjectReader.NextValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *226

           2.29.4    TAbstractObjectReader.ReadValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *227

           2.29.5    TAbstractObjectReader.BeginRootComponent                           .  .  .  .  .  .  .  .  .  .  .  .  .  227

           2.29.6    TAbstractObjectReader.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  227

           2.29.7    TAbstractObjectReader.BeginProperty                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *27

           2.29.8    TAbstractObjectReader.Read                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  228

           2.29.9    TAbstractObjectReader.ReadBinary                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *228

           2.29.10   TAbstractObjectReader.ReadFloat                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *228

           2.29.11   TAbstractObjectReader.ReadSingle                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *229

           2.29.12   TAbstractObjectReader.ReadCurrency                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *29

           2.29.13   TAbstractObjectReader.ReadDate                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *229

           2.29.14   TAbstractObjectReader.ReadIdent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *229

           2.29.15   TAbstractObjectReader.ReadInt8                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *230



                                                                  7

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.29.16   TAbstractObjectReader.ReadInt16                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *230

           2.29.17   TAbstractObjectReader.ReadInt32                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *231

           2.29.18   TAbstractObjectReader.ReadInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *231

           2.29.19   TAbstractObjectReader.ReadSet                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 231

           2.29.20   TAbstractObjectReader.ReadStr                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 232

           2.29.21   TAbstractObjectReader.ReadString                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *232

           2.29.22   TAbstractObjectReader.ReadWideString                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  232

           2.29.23   TAbstractObjectReader.SkipComponent                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *33

           2.29.24   TAbstractObjectReader.SkipValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *233

    2.30   TAbstractObjectWriter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  233

           2.30.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  233

           2.30.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  233

           2.30.3    TAbstractObjectWriter.BeginCollection                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *34

           2.30.4    TAbstractObjectWriter.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  234

           2.30.5    TAbstractObjectWriter.BeginList                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 234

           2.30.6    TAbstractObjectWriter.EndList                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 234

           2.30.7    TAbstractObjectWriter.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *34

           2.30.8    TAbstractObjectWriter.EndProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *234

           2.30.9    TAbstractObjectWriter.Write                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  235

           2.30.10   TAbstractObjectWriter.WriteBinary                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *235

           2.30.11   TAbstractObjectWriter.WriteBoolean                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *35

           2.30.12   TAbstractObjectWriter.WriteFloat                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *235

           2.30.13   TAbstractObjectWriter.WriteSingle                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *235

           2.30.14   TAbstractObjectWriter.WriteCurrency                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *36

           2.30.15   TAbstractObjectWriter.WriteDate                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *236

           2.30.16   TAbstractObjectWriter.WriteIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *236

           2.30.17   TAbstractObjectWriter.WriteInteger                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *236

           2.30.18   TAbstractObjectWriter.WriteMethodName                          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  236

           2.30.19   TAbstractObjectWriter.WriteSet                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 237

           2.30.20   TAbstractObjectWriter.WriteString                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *237

           2.30.21   TAbstractObjectWriter.WriteWideString                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  237

    2.31   TBasicAction         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  237

           2.31.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  237

           2.31.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  237

           2.31.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  238

           2.31.4    TBasicAction.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  238

           2.31.5    TBasicAction.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  238

           2.31.6    TBasicAction.HandlesTarget                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  238

           2.31.7    TBasicAction.UpdateTarget                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  239

           2.31.8    TBasicAction.ExecuteTarget                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  239



                                                                  8

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.31.9    TBasicAction.Execute             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  239

           2.31.10   TBasicAction.RegisterChanges                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 239

           2.31.11   TBasicAction.UnRegisterChanges                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *240

           2.31.12   TBasicAction.Update              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  240

           2.31.13   TBasicAction.ActionComponent                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 240

           2.31.14   TBasicAction.OnExecute                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  240

           2.31.15   TBasicAction.OnUpdate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  241

    2.32   TBasicActionLink             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  241

           2.32.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  241

           2.32.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  241

           2.32.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  241

           2.32.4    TBasicActionLink.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  242

           2.32.5    TBasicActionLink.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  242

           2.32.6    TBasicActionLink.Execute                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  242

           2.32.7    TBasicActionLink.Update               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  243

           2.32.8    TBasicActionLink.Action               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  243

           2.32.9    TBasicActionLink.OnChange                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  243

    2.33   TBinaryObjectReader              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  243

           2.33.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  243

           2.33.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  244

           2.33.3    TBinaryObjectReader.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  244

           2.33.4    TBinaryObjectReader.Destroy                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 244

           2.33.5    TBinaryObjectReader.NextValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 245

           2.33.6    TBinaryObjectReader.ReadValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 245

           2.33.7    TBinaryObjectReader.BeginRootComponent                           .  .  .  .  .  .  .  .  .  .  .  .  .  .  245

           2.33.8    TBinaryObjectReader.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *45

           2.33.9    TBinaryObjectReader.BeginProperty                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *46

           2.33.10   TBinaryObjectReader.Read                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  246

           2.33.11   TBinaryObjectReader.ReadBinary                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *246

           2.33.12   TBinaryObjectReader.ReadFloat                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 246

           2.33.13   TBinaryObjectReader.ReadSingle                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *246

           2.33.14   TBinaryObjectReader.ReadCurrency                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *247

           2.33.15   TBinaryObjectReader.ReadDate                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 247

           2.33.16   TBinaryObjectReader.ReadIdent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 247

           2.33.17   TBinaryObjectReader.ReadInt8                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 247

           2.33.18   TBinaryObjectReader.ReadInt16                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 247

           2.33.19   TBinaryObjectReader.ReadInt32                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 248

           2.33.20   TBinaryObjectReader.ReadInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 248

           2.33.21   TBinaryObjectReader.ReadSet                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 248

           2.33.22   TBinaryObjectReader.ReadStr                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 248



                                                                  9

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.33.23   TBinaryObjectReader.ReadString                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *249

           2.33.24   TBinaryObjectReader.ReadWideString                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *49

           2.33.25   TBinaryObjectReader.SkipComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *49

           2.33.26   TBinaryObjectReader.SkipValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 249

    2.34   TBinaryObjectWriter              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  249

           2.34.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  249

           2.34.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  250

           2.34.3    TBinaryObjectWriter.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  250

           2.34.4    TBinaryObjectWriter.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  250

           2.34.5    TBinaryObjectWriter.BeginCollection                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *50

           2.34.6    TBinaryObjectWriter.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *51

           2.34.7    TBinaryObjectWriter.BeginList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 251

           2.34.8    TBinaryObjectWriter.EndList                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 251

           2.34.9    TBinaryObjectWriter.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *251

           2.34.10   TBinaryObjectWriter.EndProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *251

           2.34.11   TBinaryObjectWriter.Write                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  251

           2.34.12   TBinaryObjectWriter.WriteBinary                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *252

           2.34.13   TBinaryObjectWriter.WriteBoolean                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *252

           2.34.14   TBinaryObjectWriter.WriteFloat                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 252

           2.34.15   TBinaryObjectWriter.WriteSingle                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *252

           2.34.16   TBinaryObjectWriter.WriteCurrency                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *252

           2.34.17   TBinaryObjectWriter.WriteDate                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 252

           2.34.18   TBinaryObjectWriter.WriteIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 253

           2.34.19   TBinaryObjectWriter.WriteInteger                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *253

           2.34.20   TBinaryObjectWriter.WriteMethodName                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  253

           2.34.21   TBinaryObjectWriter.WriteSet                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 253

           2.34.22   TBinaryObjectWriter.WriteString                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *253

           2.34.23   TBinaryObjectWriter.WriteWideString                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *53

    2.35   TBits       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  254

           2.35.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  254

           2.35.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  254

           2.35.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  254

           2.35.4    TBits.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  254

           2.35.5    TBits.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  255

           2.35.6    TBits.GetFSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  255

           2.35.7    TBits.SetOn          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  255

           2.35.8    TBits.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  255

           2.35.9    TBits.Clearall       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  256

           2.35.10   TBits.AndBits          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  256

           2.35.11   TBits.OrBits         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  256



                                                                 10

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.35.12   TBits.XorBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  256

           2.35.13   TBits.NotBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  257

           2.35.14   TBits.Get       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  257

           2.35.15   TBits.Grow         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  257

           2.35.16   TBits.Equals         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  258

           2.35.17   TBits.SetIndex         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  258

           2.35.18   TBits.FindFirstBit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  258

           2.35.19   TBits.FindNextBit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

           2.35.20   TBits.FindPrevBit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

           2.35.21   TBits.OpenBit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  259

           2.35.22   TBits.Bits      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  260

           2.35.23   TBits.Size      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  260

    2.36   TCollection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  260

           2.36.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  260

           2.36.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  261

           2.36.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  261

           2.36.4    TCollection.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  261

           2.36.5    TCollection.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  261

           2.36.6    TCollection.Owner           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  261

           2.36.7    TCollection.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  262

           2.36.8    TCollection.Assign          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  262

           2.36.9    TCollection.BeginUpdate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  262

           2.36.10   TCollection.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  263

           2.36.11   TCollection.EndUpdate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  263

           2.36.12   TCollection.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  263

           2.36.13   TCollection.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  264

           2.36.14   TCollection.FindItemID              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  264

           2.36.15   TCollection.Count           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  264

           2.36.16   TCollection.ItemClass            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  264

           2.36.17   TCollection.Items           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  265

    2.37   TCollectionItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

           2.37.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

           2.37.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  265

           2.37.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  266

           2.37.4    TCollectionItem.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  266

           2.37.5    TCollectionItem.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  266

           2.37.6    TCollectionItem.Collection               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  266

           2.37.7    TCollectionItem.ID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  267

           2.37.8    TCollectionItem.Index            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  267

           2.37.9    TCollectionItem.DisplayName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  267



                                                                 11

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    2.38   TComponent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  268

           2.38.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  268

           2.38.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  268

           2.38.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  269

           2.38.4    TComponent.WriteState               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  269

           2.38.5    TComponent.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  269

           2.38.6    TComponent.BeforeDestruction                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 269

           2.38.7    TComponent.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  270

           2.38.8    TComponent.DestroyComponents                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *270

           2.38.9    TComponent.Destroying               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  270

           2.38.10   TComponent.ExecuteAction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  271

           2.38.11   TComponent.FindComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  271

           2.38.12   TComponent.FreeNotification                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  271

           2.38.13   TComponent.RemoveFreeNotification                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *71

           2.38.14   TComponent.FreeOnRelease                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  272

           2.38.15   TComponent.GetParentComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *272

           2.38.16   TComponent.HasParent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  272

           2.38.17   TComponent.InsertComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 272

           2.38.18   TComponent.RemoveComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 273

           2.38.19   TComponent.SafeCallException                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 273

           2.38.20   TComponent.SetSubComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 273

           2.38.21   TComponent.UpdateAction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  273

           2.38.22   TComponent.IsImplementorOf                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 274

           2.38.23   TComponent.ReferenceInterface                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 274

           2.38.24   TComponent.Components                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  274

           2.38.25   TComponent.ComponentCount                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 274

           2.38.26   TComponent.ComponentIndex                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 275

           2.38.27   TComponent.ComponentState                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 275

           2.38.28   TComponent.ComponentStyle                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 275

           2.38.29   TComponent.DesignInfo               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  276

           2.38.30   TComponent.Owner               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  276

           2.38.31   TComponent.VCLComObject                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  276

           2.38.32   TComponent.Name                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  277

           2.38.33   TComponent.Tag            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  277

    2.39   TCustomMemoryStream                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  277

           2.39.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  277

           2.39.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  278

           2.39.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  278

           2.39.4    TCustomMemoryStream.GetSize                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 278

           2.39.5    TCustomMemoryStream.Read                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 278



                                                                 12

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.39.6    TCustomMemoryStream.Seek                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  278

           2.39.7    TCustomMemoryStream.SaveToStream                          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *79

           2.39.8    TCustomMemoryStream.SaveToFile                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *279

           2.39.9    TCustomMemoryStream.Memory                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 279

    2.40   TDataModule          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  280

           2.40.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  280

           2.40.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  280

           2.40.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  280

           2.40.4    TDataModule.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  280

           2.40.5    TDataModule.CreateNew                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  281

           2.40.6    TDataModule.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  281

           2.40.7    TDataModule.AfterConstruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 281

           2.40.8    TDataModule.BeforeDestruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 281

           2.40.9    TDataModule.DesignOffset                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  282

           2.40.10   TDataModule.DesignSize                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  282

           2.40.11   TDataModule.OnCreate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  282

           2.40.12   TDataModule.OnDestroy                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  283

           2.40.13   TDataModule.OldCreateOrder                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 283

    2.41   TFiler      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  283

           2.41.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  283

           2.41.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  283

           2.41.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  283

           2.41.4    TFiler.DefineProperty            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  284

           2.41.5    TFiler.DefineBinaryProperty                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  284

           2.41.6    TFiler.Root        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  284

           2.41.7    TFiler.LookupRoot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  284

           2.41.8    TFiler.Ancestor        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  285

           2.41.9    TFiler.IgnoreChildren            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  285

    2.42   TFileStream        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  285

           2.42.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  285

           2.42.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  285

           2.42.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  285

           2.42.4    TFileStream.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  285

           2.42.5    TFileStream.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  286

           2.42.6    TFileStream.FileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  286

    2.43   TFPList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  287

           2.43.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  287

           2.43.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  287

           2.43.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  287

           2.43.4    TFPList.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  287



                                                                 13

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.43.5    TFPList.AddList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  288

           2.43.6    TFPList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  288

           2.43.7    TFPList.Clear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  288

           2.43.8    TFPList.Delete         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  288

           2.43.9    TFPList.Error          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  289

           2.43.10   TFPList.Exchange            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  289

           2.43.11   TFPList.Expand            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  289

           2.43.12   TFPList.Extract           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  289

           2.43.13   TFPList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  290

           2.43.14   TFPList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  290

           2.43.15   TFPList.Insert         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  290

           2.43.16   TFPList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  290

           2.43.17   TFPList.Move           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  291

           2.43.18   TFPList.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  291

           2.43.19   TFPList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  291

           2.43.20   TFPList.Pack         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  291

           2.43.21   TFPList.Sort         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  292

           2.43.22   TFPList.ForEachCall              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  292

           2.43.23   TFPList.Capacity            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  292

           2.43.24   TFPList.Count          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  293

           2.43.25   TFPList.Items          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  293

           2.43.26   TFPList.List         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  293

    2.44   THandleStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  293

           2.44.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  293

           2.44.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  294

           2.44.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  294

           2.44.4    THandleStream.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  294

           2.44.5    THandleStream.Read               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  294

           2.44.6    THandleStream.Write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  294

           2.44.7    THandleStream.Seek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  295

           2.44.8    THandleStream.Handle                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  295

    2.45   TInterfacedPersistent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  295

           2.45.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  295

           2.45.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  295

           2.45.3    TInterfacedPersistent.QueryInterface                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *295

           2.45.4    TInterfacedPersistent.AfterConstruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *96

    2.46   TInterfaceList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  296

           2.46.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  296

           2.46.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  296

           2.46.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  296



                                                                 14

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.46.4    TInterfaceList.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  296

           2.46.5    TInterfaceList.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  297

           2.46.6    TInterfaceList.Clear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  297

           2.46.7    TInterfaceList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  297

           2.46.8    TInterfaceList.Exchange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  297

           2.46.9    TInterfaceList.First           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  298

           2.46.10   TInterfaceList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  298

           2.46.11   TInterfaceList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  298

           2.46.12   TInterfaceList.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  298

           2.46.13   TInterfaceList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  299

           2.46.14   TInterfaceList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  299

           2.46.15   TInterfaceList.Lock            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  299

           2.46.16   TInterfaceList.Unlock            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  299

           2.46.17   TInterfaceList.Expand            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  300

           2.46.18   TInterfaceList.Capacity             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  300

           2.46.19   TInterfaceList.Count           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  300

           2.46.20   TInterfaceList.Items           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  300

    2.47   TList    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  301

           2.47.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  301

           2.47.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  301

           2.47.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  301

           2.47.4    TList.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  301

           2.47.5    TList.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  302

           2.47.6    TList.AddList          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  302

           2.47.7    TList.Add       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  302

           2.47.8    TList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  302

           2.47.9    TList.Delete         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  303

           2.47.10   TList.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  303

           2.47.11   TList.Exchange         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  303

           2.47.12   TList.Expand         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  303

           2.47.13   TList.Extract        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  304

           2.47.14   TList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  304

           2.47.15   TList.IndexOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  304

           2.47.16   TList.Insert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  304

           2.47.17   TList.Last      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  305

           2.47.18   TList.Move         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  305

           2.47.19   TList.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  305

           2.47.20   TList.Remove         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  305

           2.47.21   TList.Pack         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  306

           2.47.22   TList.Sort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  306



                                                                 15

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.47.23   TList.Capacity         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  306

           2.47.24   TList.Count        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  307

           2.47.25   TList.Items        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  307

           2.47.26   TList.List      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  307

    2.48   TMemoryStream             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  307

           2.48.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  307

           2.48.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  308

           2.48.3    TMemoryStream.Destroy                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  308

           2.48.4    TMemoryStream.Clear              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  308

           2.48.5    TMemoryStream.LoadFromStream                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *308

           2.48.6    TMemoryStream.LoadFromFile                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 309

           2.48.7    TMemoryStream.SetSize               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  309

           2.48.8    TMemoryStream.Write                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  309

    2.49   TOwnedCollection             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  309

           2.49.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  309

           2.49.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  310

           2.49.3    TOwnedCollection.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  310

    2.50   TOwnerStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  310

           2.50.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  310

           2.50.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  310

           2.50.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  310

           2.50.4    TOwnerStream.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  310

           2.50.5    TOwnerStream.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  311

           2.50.6    TOwnerStream.Source              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  311

           2.50.7    TOwnerStream.SourceOwner                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  311

    2.51   TParser       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  311

           2.51.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  311

           2.51.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  312

           2.51.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  312

           2.51.4    TParser.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  312

           2.51.5    TParser.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  312

           2.51.6    TParser.CheckToken             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  313

           2.51.7    TParser.CheckTokenSymbol                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  313

           2.51.8    TParser.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  313

           2.51.9    TParser.ErrorFmt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  313

           2.51.10   TParser.ErrorStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  313

           2.51.11   TParser.HexToBinary              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  314

           2.51.12   TParser.NextToken           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  314

           2.51.13   TParser.SourcePos           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  314

           2.51.14   TParser.TokenComponentIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 315



                                                                 16

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.51.15   TParser.TokenFloat             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  315

           2.51.16   TParser.TokenInt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  315

           2.51.17   TParser.TokenString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  316

           2.51.18   TParser.TokenWideString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  316

           2.51.19   TParser.TokenSymbolIs               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  316

           2.51.20   TParser.FloatType           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  317

           2.51.21   TParser.SourceLine             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  317

           2.51.22   TParser.Token          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  317

    2.52   TPersistent        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  318

           2.52.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  318

           2.52.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  318

           2.52.3    TPersistent.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  318

           2.52.4    TPersistent.Assign          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  318

           2.52.5    TPersistent.GetNamePath               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  319

    2.53   TReader       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  319

           2.53.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  319

           2.53.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  320

           2.53.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  321

           2.53.4    TReader.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  321

           2.53.5    TReader.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  321

           2.53.6    TReader.BeginReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  321

           2.53.7    TReader.CheckValue             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  322

           2.53.8    TReader.DefineProperty              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

           2.53.9    TReader.DefineBinaryProperty                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 322

           2.53.10   TReader.EndOfList              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  322

           2.53.11   TReader.EndReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

           2.53.12   TReader.FixupReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  323

           2.53.13   TReader.NextValue              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  323

           2.53.14   TReader.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  323

           2.53.15   TReader.ReadBoolean              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  323

           2.53.16   TReader.ReadChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  323

           2.53.17   TReader.ReadWideChar                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

           2.53.18   TReader.ReadCollection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

           2.53.19   TReader.ReadComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  324

           2.53.20   TReader.ReadComponents                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  324

           2.53.21   TReader.ReadFloat              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  324

           2.53.22   TReader.ReadSingle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  325

           2.53.23   TReader.ReadCurrency                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  325

           2.53.24   TReader.ReadDate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  325

           2.53.25   TReader.ReadIdent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  325



                                                                 17

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.53.26   TReader.ReadInteger              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  325

           2.53.27   TReader.ReadInt64              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  326

           2.53.28   TReader.ReadListBegin               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  326

           2.53.29   TReader.ReadListEnd              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  326

           2.53.30   TReader.ReadRootComponent                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 326

           2.53.31   TReader.ReadString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  326

           2.53.32   TReader.ReadWideString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  327

           2.53.33   TReader.ReadValue              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  327

           2.53.34   TReader.CopyValue              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  327

           2.53.35   TReader.Driver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  327

           2.53.36   TReader.Owner          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  327

           2.53.37   TReader.Parent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  328

           2.53.38   TReader.OnError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  328

           2.53.39   TReader.OnPropertyNotFound                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 328

           2.53.40   TReader.OnFindMethod                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  328

           2.53.41   TReader.OnSetMethodProperty                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 329

           2.53.42   TReader.OnSetName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  329

           2.53.43   TReader.OnReferenceName                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  329

           2.53.44   TReader.OnAncestorNotFound                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 329

           2.53.45   TReader.OnCreateComponent                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 329

           2.53.46   TReader.OnFindComponentClass                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *330

           2.53.47   TReader.OnReadStringProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 330

    2.54   TRecall       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  330

           2.54.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  330

           2.54.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  331

           2.54.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  331

           2.54.4    TRecall.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  331

           2.54.5    TRecall.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  331

           2.54.6    TRecall.Store        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  331

           2.54.7    TRecall.Forget         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  332

           2.54.8    TRecall.Reference           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  332

    2.55   TResourceStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  332

           2.55.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  332

           2.55.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  332

           2.55.3    TResourceStream.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  332

           2.55.4    TResourceStream.CreateFromID                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 333

           2.55.5    TResourceStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  333

    2.56   TStream       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  333

           2.56.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  333

           2.56.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  334



                                                                 18

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.56.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  334

           2.56.4    TStream.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  334

           2.56.5    TStream.Write          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  335

           2.56.6    TStream.Seek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  335

           2.56.7    TStream.ReadBuffer             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  336

           2.56.8    TStream.WriteBuffer            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  336

           2.56.9    TStream.CopyFrom               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  336

           2.56.10   TStream.ReadComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  337

           2.56.11   TStream.ReadComponentRes                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  337

           2.56.12   TStream.WriteComponent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  337

           2.56.13   TStream.WriteComponentRes                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  338

           2.56.14   TStream.WriteDescendent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  338

           2.56.15   TStream.WriteDescendentRes                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  338

           2.56.16   TStream.WriteResourceHeader                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 338

           2.56.17   TStream.FixupResourceHeader                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 339

           2.56.18   TStream.ReadResHeader                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  339

           2.56.19   TStream.ReadByte            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  339

           2.56.20   TStream.ReadWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  340

           2.56.21   TStream.ReadDWord                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  340

           2.56.22   TStream.ReadAnsiString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  340

           2.56.23   TStream.WriteByte              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  340

           2.56.24   TStream.WriteWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  341

           2.56.25   TStream.WriteDWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  341

           2.56.26   TStream.WriteAnsiString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  341

           2.56.27   TStream.Position          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  342

           2.56.28   TStream.Size         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  342

    2.57   TStreamAdapter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  342

           2.57.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  342

           2.57.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  343

           2.57.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  343

           2.57.4    TStreamAdapter.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  343

           2.57.5    TStreamAdapter.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  343

           2.57.6    TStreamAdapter.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  344

           2.57.7    TStreamAdapter.Write                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  344

           2.57.8    TStreamAdapter.Seek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  344

           2.57.9    TStreamAdapter.SetSize              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  344

           2.57.10   TStreamAdapter.CopyTo                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  345

           2.57.11   TStreamAdapter.Commit                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  345

           2.57.12   TStreamAdapter.Revert               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  345

           2.57.13   TStreamAdapter.LockRegion                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  345



                                                                 19

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.57.14   TStreamAdapter.UnlockRegion                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 346

           2.57.15   TStreamAdapter.Stat              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  346

           2.57.16   TStreamAdapter.Clone                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  346

           2.57.17   TStreamAdapter.Stream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  346

           2.57.18   TStreamAdapter.StreamOwnership                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *347

    2.58   TStringList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  347

           2.58.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  347

           2.58.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  347

           2.58.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  347

           2.58.4    TStringList.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  347

           2.58.5    TStringList.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  348

           2.58.6    TStringList.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  348

           2.58.7    TStringList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  348

           2.58.8    TStringList.Exchange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  348

           2.58.9    TStringList.Find          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  349

           2.58.10   TStringList.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  349

           2.58.11   TStringList.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  349

           2.58.12   TStringList.Sort          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  349

           2.58.13   TStringList.CustomSort              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  350

           2.58.14   TStringList.Duplicates           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  350

           2.58.15   TStringList.Sorted          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350

           2.58.16   TStringList.CaseSensitive             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  351

           2.58.17   TStringList.OnChange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  351

           2.58.18   TStringList.OnChanging              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  351

    2.59   TStrings      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  351

           2.59.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  351

           2.59.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  352

           2.59.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  353

           2.59.4    TStrings.Destroy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  353

           2.59.5    TStrings.Add         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  353

           2.59.6    TStrings.AddObject             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  353

           2.59.7    TStrings.Append           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  354

           2.59.8    TStrings.AddStrings            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  354

           2.59.9    TStrings.Assign        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  354

           2.59.10   TStrings.BeginUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

           2.59.11   TStrings.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  355

           2.59.12   TStrings.Delete        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  355

           2.59.13   TStrings.EndUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  356

           2.59.14   TStrings.Equals           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  356

           2.59.15   TStrings.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  356



                                                                 20

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.59.16   TStrings.GetText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  357

           2.59.17   TStrings.IndexOf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  357

           2.59.18   TStrings.IndexOfName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  357

           2.59.19   TStrings.IndexOfObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  358

           2.59.20   TStrings.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  358

           2.59.21   TStrings.InsertObject            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  358

           2.59.22   TStrings.LoadFromFile               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  359

           2.59.23   TStrings.LoadFromStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  359

           2.59.24   TStrings.Move          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  359

           2.59.25   TStrings.SaveToFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  360

           2.59.26   TStrings.SaveToStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  360

           2.59.27   TStrings.SetText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  360

           2.59.28   TStrings.GetNameValue               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  361

           2.59.29   TStrings.ExtractName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  361

           2.59.30   TStrings.TextLineBreakStyle                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  361

           2.59.31   TStrings.Delimiter          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  362

           2.59.32   TStrings.DelimitedText              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  362

           2.59.33   TStrings.QuoteChar             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  362

           2.59.34   TStrings.NameValueSeparator                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 362

           2.59.35   TStrings.ValueFromIndex               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  362

           2.59.36   TStrings.Capacity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  363

           2.59.37   TStrings.CommaText               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  363

           2.59.38   TStrings.Count         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  364

           2.59.39   TStrings.Names         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  364

           2.59.40   TStrings.Objects          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  364

           2.59.41   TStrings.Values        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  365

           2.59.42   TStrings.Strings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  365

           2.59.43   TStrings.Text        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  366

           2.59.44   TStrings.StringsAdapter             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  366

    2.60   TStringStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  366

           2.60.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  366

           2.60.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  367

           2.60.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  367

           2.60.4    TStringStream.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  367

           2.60.5    TStringStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  367

           2.60.6    TStringStream.ReadString                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  367

           2.60.7    TStringStream.Seek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  368

           2.60.8    TStringStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  368

           2.60.9    TStringStream.WriteString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  368

           2.60.10   TStringStream.DataString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  368



                                                                 21

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    2.61   TTextObjectWriter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  368

           2.61.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  368

    2.62   TThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  369

           2.62.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  369

           2.62.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  369

           2.62.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  369

           2.62.4    TThread.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  369

           2.62.5    TThread.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  369

           2.62.6    TThread.AfterConstruction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  370

           2.62.7    TThread.Resume            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  370

           2.62.8    TThread.Suspend             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  370

           2.62.9    TThread.Terminate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  370

           2.62.10   TThread.WaitFor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  370

           2.62.11   TThread.FreeOnTerminate                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  370

           2.62.12   TThread.Handle            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  371

           2.62.13   TThread.Priority          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  371

           2.62.14   TThread.Suspended              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  371

           2.62.15   TThread.ThreadID            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  371

           2.62.16   TThread.OnTerminate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  371

           2.62.17   TThread.FatalException              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  372

    2.63   TThreadList          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  372

           2.63.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  372

           2.63.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  372

           2.63.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  372

           2.63.4    TThreadList.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  372

           2.63.5    TThreadList.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  372

           2.63.6    TThreadList.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  373

           2.63.7    TThreadList.Clear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  373

           2.63.8    TThreadList.LockList             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  373

           2.63.9    TThreadList.Remove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  373

           2.63.10   TThreadList.UnlockList              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  373

           2.63.11   TThreadList.Duplicates              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  374

    2.64   TWriter       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  374

           2.64.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  374

           2.64.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  374

           2.64.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  375

           2.64.4    TWriter.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  375

           2.64.5    TWriter.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  375

           2.64.6    TWriter.DefineProperty              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  375

           2.64.7    TWriter.DefineBinaryProperty                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 375



                                                                 22

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.64.8    TWriter.Write          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  376

           2.64.9    TWriter.WriteBoolean             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  376

           2.64.10   TWriter.WriteCollection             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  376

           2.64.11   TWriter.WriteComponent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  376

           2.64.12   TWriter.WriteChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  376

           2.64.13   TWriter.WriteWideChar               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  377

           2.64.14   TWriter.WriteDescendent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  377

           2.64.15   TWriter.WriteFloat             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  377

           2.64.16   TWriter.WriteSingle            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  377

           2.64.17   TWriter.WriteCurrency               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  377

           2.64.18   TWriter.WriteDate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  378

           2.64.19   TWriter.WriteIdent             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  378

           2.64.20   TWriter.WriteInteger             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  378

           2.64.21   TWriter.WriteListBegin              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  378

           2.64.22   TWriter.WriteListEnd             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  378

           2.64.23   TWriter.WriteRootComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 378

           2.64.24   TWriter.WriteString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  379

           2.64.25   TWriter.WriteWideString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  379

           2.64.26   TWriter.RootAncestor             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  379

           2.64.27   TWriter.OnFindAncestor                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  379

           2.64.28   TWriter.OnWriteMethodProperty                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *379

           2.64.29   TWriter.OnWriteStringProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 380

           2.64.30   TWriter.Driver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  380

           2.64.31   TWriter.PropertyPath             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  380


3    Reference for unit 'Crt'                                                                                           381

    3.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  381

    3.2    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  381

           3.2.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  381

           3.2.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  384

           3.2.3     Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  384

    3.3    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  385

           3.3.1     AssignCrt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  385

           3.3.2     ClrEol     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  386

           3.3.3     ClrScr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  386

           3.3.4     cursorbig       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  387

           3.3.5     cursoroff     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  387

           3.3.6     cursoron      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  387

           3.3.7     Delay      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  388

           3.3.8     DelLine       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  388
                                                                 23

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           3.3.9     GotoXY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  389

           3.3.10    HighVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  389

           3.3.11    InsLine       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  390

           3.3.12    KeyPressed         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  391

           3.3.13    LowVideo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  391

           3.3.14    NormVideo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  391

           3.3.15    NoSound         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  392

           3.3.16    ReadKey         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  392

           3.3.17    Sound      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  393

           3.3.18    TextBackground            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  393

           3.3.19    TextColor       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  394

           3.3.20    TextMode        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  394

           3.3.21    WhereX        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  395

           3.3.22    WhereY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  395

           3.3.23    Window        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  396


4    Reference for unit 'dateutils'                                                                                     397

    4.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  397

    4.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  397

    4.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  397

           4.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  397

    4.4    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  399

           4.4.1     CompareDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  399

           4.4.2     CompareDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  400

           4.4.3     CompareTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  401

           4.4.4     DateOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  402

           4.4.5     DateTimeToJulianDate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  403

           4.4.6     DateTimeToMac             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  403

           4.4.7     DateTimeToModifiedJulianDate                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 403

           4.4.8     DateTimeToUnix            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  404

           4.4.9     DayOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  404

           4.4.10    DayOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  404

           4.4.11    DayOfTheWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  404

           4.4.12    DayOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  405

           4.4.13    DaysBetween          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  405

           4.4.14    DaysInAMonth           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  406

           4.4.15    DaysInAYear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  407

           4.4.16    DaysInMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  407

           4.4.17    DaysInYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  408

           4.4.18    DaySpan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  408
                                                                 24

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           4.4.19    DecodeDateDay             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  409

           4.4.20    DecodeDateMonthWeek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  410

           4.4.21    DecodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  410

           4.4.22    DecodeDateWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  411

           4.4.23    DecodeDayOfWeekInMonth                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  412

           4.4.24    EncodeDateDay             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  412

           4.4.25    EncodeDateMonthWeek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

           4.4.26    EncodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  413

           4.4.27    EncodeDateWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  413

           4.4.28    EncodeDayOfWeekInMonth                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  414

           4.4.29    EndOfADay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  414

           4.4.30    EndOfAMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  415

           4.4.31    EndOfAWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  415

           4.4.32    EndOfAYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  416

           4.4.33    EndOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  417

           4.4.34    EndOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  417

           4.4.35    EndOfTheWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  418

           4.4.36    EndOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  418

           4.4.37    HourOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  419

           4.4.38    HourOfTheDay           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  419

           4.4.39    HourOfTheMonth              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  420

           4.4.40    HourOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  420

           4.4.41    HourOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  420

           4.4.42    HoursBetween           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  420

           4.4.43    HourSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  421

           4.4.44    IncDay        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  422

           4.4.45    IncHour       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  423

           4.4.46    IncMilliSecond         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  423

           4.4.47    IncMinute       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  424

           4.4.48    IncSecond       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  424

           4.4.49    IncWeek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  425

           4.4.50    IncYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  425

           4.4.51    InvalidDateDayError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  426

           4.4.52    InvalidDateMonthWeekError                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  426

           4.4.53    InvalidDateTimeError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  426

           4.4.54    InvalidDateWeekError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  427

           4.4.55    InvalidDayOfWeekInMonthError                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 427

           4.4.56    IsInLeapYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  428

           4.4.57    IsPM       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  428

           4.4.58    IsSameDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  429



                                                                 25

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           4.4.59    IsToday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  429

           4.4.60    IsValidDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  430

           4.4.61    IsValidDateDay         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  430

           4.4.62    IsValidDateMonthWeek                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  431

           4.4.63    IsValidDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  432

           4.4.64    IsValidDateWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  433

           4.4.65    IsValidTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  433

           4.4.66    JulianDateToDateTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  434

           4.4.67    MacTimeStampToUnix                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  434

           4.4.68    MacToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  434

           4.4.69    MilliSecondOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  434

           4.4.70    MilliSecondOfTheDay              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  435

           4.4.71    MilliSecondOfTheHour             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  435

           4.4.72    MilliSecondOfTheMinute                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  435

           4.4.73    MilliSecondOfTheMonth               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  436

           4.4.74    MilliSecondOfTheSecond                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  436

           4.4.75    MilliSecondOfTheWeek                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  436

           4.4.76    MilliSecondOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  437

           4.4.77    MilliSecondsBetween            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  437

           4.4.78    MilliSecondSpan           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  438

           4.4.79    MinuteOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  439

           4.4.80    MinuteOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  439

           4.4.81    MinuteOfTheHour             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  439

           4.4.82    MinuteOfTheMonth               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  440

           4.4.83    MinuteOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  440

           4.4.84    MinuteOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  440

           4.4.85    MinutesBetween            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  441

           4.4.86    MinuteSpan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  442

           4.4.87    ModifiedJulianDateToDateTime                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 442

           4.4.88    MonthOf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  443

           4.4.89    MonthOfTheYear            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  443

           4.4.90    MonthsBetween          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  443

           4.4.91    MonthSpan          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  444

           4.4.92    NthDayOfWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  445

           4.4.93    PreviousDayOfWeek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  446

           4.4.94    RecodeDate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  446

           4.4.95    RecodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  447

           4.4.96    RecodeDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  448

           4.4.97    RecodeHour         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  448

           4.4.98    RecodeMilliSecond           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  449



                                                                 26

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           4.4.99    RecodeMinute           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  450

           4.4.100   RecodeMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  450

           4.4.101   RecodeSecond         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  451

           4.4.102   RecodeTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  452

           4.4.103   RecodeYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  452

           4.4.104   SameDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  453

           4.4.105   SameDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  454

           4.4.106   SameTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  455

           4.4.107   ScanDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  455

           4.4.108   SecondOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  456

           4.4.109   SecondOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  456

           4.4.110   SecondOfTheHour             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  456

           4.4.111   SecondOfTheMinute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  457

           4.4.112   SecondOfTheMonth               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  457

           4.4.113   SecondOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  457

           4.4.114   SecondOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  458

           4.4.115   SecondsBetween            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  458

           4.4.116   SecondSpan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  459

           4.4.117   StartOfADay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  460

           4.4.118   StartOfAMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  461

           4.4.119   StartOfAWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  461

           4.4.120   StartOfAYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  462

           4.4.121   StartOfTheDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  462

           4.4.122   StartOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  463

           4.4.123   StartOfTheWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  463

           4.4.124   StartOfTheYear            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  464

           4.4.125   TimeOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  464

           4.4.126   Today      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  465

           4.4.127   Tomorrow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  465

           4.4.128   TryEncodeDateDay               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  466

           4.4.129   TryEncodeDateMonthWeek                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  466

           4.4.130   TryEncodeDateTime              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  467

           4.4.131   TryEncodeDateWeek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  468

           4.4.132   TryEncodeDayOfWeekInMonth                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 468

           4.4.133   TryJulianDateToDateTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  469

           4.4.134   TryModifiedJulianDateToDateTime                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *469

           4.4.135   TryRecodeDateTime              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  470

           4.4.136   UnixTimeStampToMac                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  471

           4.4.137   UnixToDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  471

           4.4.138   WeekOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  471



                                                                 27

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           4.4.139   WeekOfTheMonth              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  471

           4.4.140   WeekOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  472

           4.4.141   WeeksBetween           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  473

           4.4.142   WeeksInAYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  474

           4.4.143   WeeksInYear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  474

           4.4.144   WeekSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  475

           4.4.145   WithinPastDays            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  476

           4.4.146   WithinPastHours           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  477

           4.4.147   WithinPastMilliSeconds              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  478

           4.4.148   WithinPastMinutes           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  479

           4.4.149   WithinPastMonths            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  480

           4.4.150   WithinPastSeconds           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  480

           4.4.151   WithinPastWeeks           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  481

           4.4.152   WithinPastYears           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  482

           4.4.153   YearOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  483

           4.4.154   YearsBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  484

           4.4.155   YearSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  485

           4.4.156   Yesterday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  486


5    Reference for unit 'Dos'                                                                                           487

    5.1    System information           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  487

    5.2    Process handling          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  487

    5.3    Directory and disk handling              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  487

    5.4    File handling        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  488

    5.5    File open mode constants.             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  488

    5.6    File attributes      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  488

    5.7    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  489

    5.8    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  489

    5.9    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  489

           5.9.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  489

           5.9.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  491

           5.9.3     Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  493

    5.10   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  494

           5.10.1    AddDisk       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  494

           5.10.2    DiskFree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  494

           5.10.3    DiskSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  495

           5.10.4    DosExitCode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  496

           5.10.5    DosVersion         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  496

           5.10.6    DTToUnixDate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  497

           5.10.7    EnvCount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  497
                                                                 28

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           5.10.8    EnvStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  498

           5.10.9    Exec     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  498

           5.10.10   FExpand         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  498

           5.10.11   FindClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  499

           5.10.12   FindFirst       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  499

           5.10.13   FindNext        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  500

           5.10.14   FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  500

           5.10.15   FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  501

           5.10.16   GetCBreak          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  502

           5.10.17   GetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  502

           5.10.18   GetEnv        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  503

           5.10.19   GetFAttr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  503

           5.10.20   GetFTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  504

           5.10.21   GetIntVec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  505

           5.10.22   GetLongName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  505

           5.10.23   GetMsCount           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  506

           5.10.24   GetShortName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  506

           5.10.25   GetTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  506

           5.10.26   GetVerify       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  507

           5.10.27   Intr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  507

           5.10.28   Keep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  508

           5.10.29   MSDos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  508

           5.10.30   PackTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  508

           5.10.31   SetCBreak          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  509

           5.10.32   SetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  509

           5.10.33   SetFAttr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  510

           5.10.34   SetFTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  510

           5.10.35   SetIntVec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  510

           5.10.36   SetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  511

           5.10.37   SetVerify       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  511

           5.10.38   SwapVectors          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  511

           5.10.39   UnixDateToDt           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  512

           5.10.40   UnpackTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  512

           5.10.41   weekday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  512


6    Reference for unit 'dxeload'                                                                                       513

    6.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  513

    6.2    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  513

           6.2.1     dxe_load      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  513


7    Reference for unit 'dynlibs'                                                                                       514



                                                                 29

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    7.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  514

    7.2    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  514

           7.2.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  514

           7.2.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  514

    7.3    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  515

           7.3.1     FreeLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  515

           7.3.2     GetProcAddress            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  515

           7.3.3     GetProcedureAddress              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  515

           7.3.4     LoadLibrary          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  515

           7.3.5     SafeLoadLibrary           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  516

           7.3.6     UnloadLibrary          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  516


8    Reference for unit 'emu387'                                                                                        517

    8.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  517

    8.2    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  517

           8.2.1     npxsetup        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  517


9    Reference for unit 'getopts'                                                                                       519

    9.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  519

    9.2    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  519

           9.2.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  519

           9.2.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  520

           9.2.3     Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  520

    9.3    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  521

           9.3.1     GetLongOpts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  521

           9.3.2     GetOpt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  521


10   Reference for unit 'go32'                                                                                          524

    10.1   Real mode callbacks            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  524

    10.2   Executing software interrupts              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  525

    10.3   Software interrupts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  525

    10.4   Hardware interrupts            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  525

    10.5   Disabling interrupts           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  526

    10.6   Creating your own interrupt handlers                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  526

    10.7   Protected mode interrupts vs.  Real mode interrupts                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  526

    10.8   Handling interrupts with DPMI                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  526

    10.9   Interrupt redirection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  526

    10.10  Processor access          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  526

    10.11  I/O port access         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  527

    10.12  dos memory access            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  527

    10.13  FPC specialities          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  527
                                                                 30

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    10.14  Selectors and descriptors           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  527

    10.15  What is DPMI            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  528

    10.16  Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  528

    10.17  Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  528

           10.17.1   Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  528

           10.17.2   Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  531

           10.17.3   Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  531

    10.18  Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  532

           10.18.1   allocate_ldt_descriptors         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  532

           10.18.2   allocate_memory_block            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  534

           10.18.3   copyfromdos          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  534

           10.18.4   copytodos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  535

           10.18.5   create_code_segment_alias_descriptor                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *535

           10.18.6   disable    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  535

           10.18.7   dpmi_dosmemfillchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  536

           10.18.8   dpmi_dosmemfillword              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  536

           10.18.9   dpmi_dosmemget            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  536

           10.18.10  dpmi_dosmemmove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  536

           10.18.11  dpmi_dosmemput            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  537

           10.18.12  enable     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  537

           10.18.13  free_ldt_descriptor         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  537

           10.18.14  free_memory_block           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  538

           10.18.15  free_rm_callback          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  538

           10.18.16  get_cs     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  538

           10.18.17  get_descriptor_access_right           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  539

           10.18.18  get_ds     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  539

           10.18.19  get_exception_handler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  539

           10.18.20  get_linear_addr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  539

           10.18.21  get_meminfo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  540

           10.18.22  get_next_selector_increment_value               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 541

           10.18.23  get_page_size        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  541

           10.18.24  get_pm_exception_handler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  542

           10.18.25  get_pm_interrupt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  542

           10.18.26  get_rm_callback        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  542

           10.18.27  get_rm_interrupt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  545

           10.18.28  get_run_mode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  546

           10.18.29  get_segment_base_address              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  546

           10.18.30  get_segment_limit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  547

           10.18.31  get_ss     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  547

           10.18.32  global_dos_alloc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  548



                                                                 31

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           10.18.33  global_dos_free        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  549

           10.18.34  inportb       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  550

           10.18.35  inportl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  550

           10.18.36  inportw       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  550

           10.18.37  lock_code       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  551

           10.18.38  lock_data       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  551

           10.18.39  lock_linear_region        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  551

           10.18.40  map_device_in_memory_block                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  552

           10.18.41  outportb      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  552

           10.18.42  outportl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  553

           10.18.43  outportw        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  553

           10.18.44  realintr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  553

           10.18.45  request_linear_region          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  554

           10.18.46  segment_to_descriptor            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  554

           10.18.47  seg_fillchar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  555

           10.18.48  seg_fillword       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  556

           10.18.49  seg_move        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  556

           10.18.50  set_descriptor_access_right           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  557

           10.18.51  set_exception_handler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  557

           10.18.52  set_pm_exception_handler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  557

           10.18.53  set_pm_interrupt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  557

           10.18.54  set_rm_interrupt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  558

           10.18.55  set_segment_base_address              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  559

           10.18.56  set_segment_limit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  559

           10.18.57  tb_offset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  560

           10.18.58  tb_segment         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  560

           10.18.59  tb_size    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  560

           10.18.60  transfer_buffer        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  560

           10.18.61  unlock_code        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  561

           10.18.62  unlock_data        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  561

           10.18.63  unlock_linear_region           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  561


11   Reference for unit 'gpm'                                                                                           563

    11.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  563

    11.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  563

    11.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  563

           11.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  563

           11.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  565

           11.3.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  567

    11.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  568
                                                                 32

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           11.4.1    Gpm_AnyDouble             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  568

           11.4.2    Gpm_AnySingle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  568

           11.4.3    Gpm_AnyTriple          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  568

           11.4.4    gpm_close       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  569

           11.4.5    gpm_fitvalues        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  569

           11.4.6    gpm_fitvaluesM         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  569

           11.4.7    gpm_getevent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  569

           11.4.8    gpm_getsnapshot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  571

           11.4.9    gpm_lowerroi         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  571

           11.4.10   gpm_open        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  571

           11.4.11   gpm_poproi         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  572

           11.4.12   gpm_pushroi          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  572

           11.4.13   gpm_raiseroi       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  572

           11.4.14   gpm_repeat         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  572

           11.4.15   Gpm_StrictDouble            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  573

           11.4.16   Gpm_StrictSingle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  573

           11.4.17   Gpm_StrictTriple          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  573


12   Reference for unit 'Graph'                                                                                         574

    12.1   Categorized functions:  Text and font handling                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *74

    12.2   Categorized functions:  Filled drawings                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 574

    12.3   Categorized functions:  Drawing primitives                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *574

    12.4   Categorized functions:  Color management                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *574

    12.5   Categorized functions:  Screen management                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *575

    12.6   Categorized functions:  Initialization               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  575

    12.7   Target specific issues:  Linux           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  575

    12.8   Target specific issues:  DOS             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  577

    12.9   A word about mode selection                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  577

    12.10  Requirements         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  579

    12.11  Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  579

    12.12  Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  579

           12.12.1   Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  579

           12.12.2   Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  594

           12.12.3   Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  599

    12.13  Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  602

           12.13.1   Arc      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  602

           12.13.2   Bar      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  602

           12.13.3   Bar3D      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  602

           12.13.4   ClearDevice        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  603

           12.13.5   Closegraph         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  603
                                                                 33

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           12.13.6   DetectGraph          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  603

           12.13.7   DrawPoly        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  603

           12.13.8   Ellipse    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  604

           12.13.9   FillEllipse     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  604

           12.13.10  FillPoly      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  604

           12.13.11  FloodFill       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  604

           12.13.12  GetArcCoords           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  605

           12.13.13  GetAspectRatio            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  605

           12.13.14  GetBkColor         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  605

           12.13.15  GetColor        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  605

           12.13.16  GetDefaultPalette           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  606

           12.13.17  GetDirectVideo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  606

           12.13.18  GetDriverName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  606

           12.13.19  GetFillPattern         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  606

           12.13.20  GetFillSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  607

           12.13.21  GetGraphMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  607

           12.13.22  GetLineSettings           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  607

           12.13.23  GetMaxColor          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  607

           12.13.24  GetMaxMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  608

           12.13.25  GetMaxX         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  608

           12.13.26  GetMaxY         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  608

           12.13.27  GetModeName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  608

           12.13.28  GetModeRange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  609

           12.13.29  GetPalette         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  609

           12.13.30  GetPaletteSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  609

           12.13.31  GetTextSettings           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  609

           12.13.32  GetViewSettings           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  610

           12.13.33  GetX       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  610

           12.13.34  GetY       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  610

           12.13.35  GraphDefaults          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  610

           12.13.36  GraphErrorMsg          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  611

           12.13.37  GraphResult          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  611

           12.13.38  InitGraph       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  611

           12.13.39  InstallUserDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  612

           12.13.40  InstallUserFont        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  612

           12.13.41  LineRel       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  612

           12.13.42  LineTo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  613

           12.13.43  MoveRel       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  613

           12.13.44  MoveTo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  613

           12.13.45  OutText       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  614



                                                                 34

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           12.13.46  PieSlice      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  614

           12.13.47  queryadapterinfo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  614

           12.13.48  Rectangle       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  614

           12.13.49  RegisterBGIDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  615

           12.13.50  RegisterBGIfont           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  615

           12.13.51  RestoreCrtMode            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  615

           12.13.52  Sector     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  615

           12.13.53  SetAspectRatio         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  616

           12.13.54  SetBkColor         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  616

           12.13.55  SetColor      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  616

           12.13.56  SetDirectVideo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  616

           12.13.57  SetFillPattern       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  617

           12.13.58  SetFillStyle       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  617

           12.13.59  SetGraphMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  617

           12.13.60  SetLineStyle         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  618

           12.13.61  SetPalette      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  618

           12.13.62  SetTextJustify         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  618

           12.13.63  SetTextStyle         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  619

           12.13.64  SetUserCharSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  620

           12.13.65  SetViewPort          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  620

           12.13.66  SetWriteMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  620

           12.13.67  TextHeight         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  621

           12.13.68  TextWidth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  621


13   Reference for unit 'heaptrc'                                                                                       622

    13.1   Controlling HeapTrc with environment variables                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  622

    13.2   HeapTrc Usage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  622

    13.3   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  623

    13.4   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  623

           13.4.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  623

           13.4.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  624

    13.5   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  625

           13.5.1    DumpHeap           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  625

           13.5.2    SetHeapExtraInfo            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  625

           13.5.3    SetHeapTraceOutput             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  626


14   Reference for unit 'ipc'                                                                                           628

    14.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  628

    14.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  628

    14.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  628

           14.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  628



                                                                 35

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           14.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  631

    14.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  635

           14.4.1    ftok     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  635

           14.4.2    msgctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  635

           14.4.3    msgget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  638

           14.4.4    msgrcv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  638

           14.4.5    msgsnd        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  639

           14.4.6    semctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  639

           14.4.7    semget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  644

           14.4.8    semop      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  644

           14.4.9    shmat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  645

           14.4.10   shmctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  646

           14.4.11   shmdt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  648

           14.4.12   shmget        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  648


15   Reference for unit 'keyboard'                                                                                      649

    15.1   Unix specific notes          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  649

    15.2   Writing a keyboard driver             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  650

    15.3   Keyboard scan codes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  651

    15.4   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  651

    15.5   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  651

           15.5.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  651

           15.5.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  656

    15.6   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  657

           15.6.1    AddSequence          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  657

           15.6.2    DoneKeyboard           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  657

           15.6.3    FindSequence         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  657

           15.6.4    FunctionKeyName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  658

           15.6.5    GetKeyboardDriver              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  658

           15.6.6    GetKeyEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  659

           15.6.7    GetKeyEventChar             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  659

           15.6.8    GetKeyEventCode             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  660

           15.6.9    GetKeyEventFlags            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  661

           15.6.10   GetKeyEventShiftState               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  661

           15.6.11   GetKeyEventUniCode               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  662

           15.6.12   InitKeyboard         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  662

           15.6.13   IsFunctionKey          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  662

           15.6.14   KeyEventToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  663

           15.6.15   KeyPressed         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  663

           15.6.16   PollKeyEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  664
                                                                 36

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           15.6.17   PollShiftStateEvent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  664

           15.6.18   PutKeyEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  665

           15.6.19   RawReadKey           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  666

           15.6.20   RawReadString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  666

           15.6.21   RestoreStartMode            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  666

           15.6.22   SetKeyboardDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  666

           15.6.23   ShiftStateToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  667

           15.6.24   TranslateKeyEvent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  667

           15.6.25   TranslateKeyEventUniCode                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  667


16   Reference for unit 'Linux'                                                                                         670

    16.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  670

    16.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  670

    16.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  670

           16.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  670

           16.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  682

    16.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  684

           16.4.1    capget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  684

           16.4.2    capset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  684

           16.4.3    epoll_create       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  684

           16.4.4    epoll_ctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  685

           16.4.5    epoll_wait      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  685

           16.4.6    futex_op      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  686

           16.4.7    Sysinfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  686


17   Reference for unit 'math'                                                                                          688

    17.1   Geometrical functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  688

    17.2   Statistical functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  688

    17.3   Number converting            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  689

    17.4   Exponential and logarithmic functions                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 689

    17.5   Hyperbolic functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  689

    17.6   Trigoniometric functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  689

    17.7   Angle unit conversion            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  689

    17.8   Min/max determination               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  689

    17.9   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  690

    17.10  Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  690

    17.11  Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  690

           17.11.1   Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  690

           17.11.2   Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  692

    17.12  Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  694

           17.12.1   arccos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  694



                                                                 37

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           17.12.2   arccosh       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  694

           17.12.3   arcosh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  695

           17.12.4   arcsin     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  695

           17.12.5   arcsinh       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  696

           17.12.6   arctan2       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  696

           17.12.7   arctanh       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  697

           17.12.8   arsinh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  697

           17.12.9   artanh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  697

           17.12.10  ceil  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  698

           17.12.11  ClearExceptions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  698

           17.12.12  CompareValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  698

           17.12.13  cosecant      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  699

           17.12.14  cosh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  699

           17.12.15  cot   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  700

           17.12.16  cotan      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  700

           17.12.17  csc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  700

           17.12.18  cycletorad      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  701

           17.12.19  degtograd       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  701

           17.12.20  degtorad      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  702

           17.12.21  DivMod        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  702

           17.12.22  EnsureRange          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  702

           17.12.23  floor    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  703

           17.12.24  Frexp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  703

           17.12.25  GetExceptionMask            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  704

           17.12.26  GetPrecisionMode            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  704

           17.12.27  GetRoundMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  704

           17.12.28  gradtodeg       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  704

           17.12.29  gradtorad       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  705

           17.12.30  hypot      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  705

           17.12.31  ifthen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  706

           17.12.32  InRange       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  706

           17.12.33  intpower      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  706

           17.12.34  IsInfinite      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  707

           17.12.35  IsNan      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  707

           17.12.36  IsZero     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  708

           17.12.37  ldexp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  708

           17.12.38  lnxp1      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  708

           17.12.39  log10    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  709

           17.12.40  log2     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  709

           17.12.41  logn     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  710



                                                                 38

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           17.12.42  Max      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  711

           17.12.43  MaxIntValue          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  711

           17.12.44  maxvalue        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  712

           17.12.45  mean       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  713

           17.12.46  meanandstddev          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  713

           17.12.47  Min      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  714

           17.12.48  MinIntValue          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  715

           17.12.49  minvalue        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  716

           17.12.50  momentskewkurtosis             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  716

           17.12.51  norm     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  717

           17.12.52  operator **(float, float):  float          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  718

           17.12.53  operator **(Int64, Int64):  Int64            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 718

           17.12.54  popnstddev         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  718

           17.12.55  popnvariance         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  719

           17.12.56  power      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  720

           17.12.57  radtocycle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  720

           17.12.58  radtodeg      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  721

           17.12.59  radtograd       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  721

           17.12.60  randg      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  722

           17.12.61  RoundTo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  722

           17.12.62  SameValue          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  723

           17.12.63  sec   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  723

           17.12.64  secant     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  723

           17.12.65  SetExceptionMask            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  724

           17.12.66  SetPrecisionMode            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  724

           17.12.67  SetRoundMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  724

           17.12.68  Sign     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  724

           17.12.69  SimpleRoundTo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  724

           17.12.70  sincos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  725

           17.12.71  sinh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  725

           17.12.72  stddev     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  726

           17.12.73  sum      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  727

           17.12.74  sumInt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  727

           17.12.75  sumofsquares         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  727

           17.12.76  sumsandsquares         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  728

           17.12.77  tan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  729

           17.12.78  tanh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  730

           17.12.79  totalvariance        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  730

           17.12.80  variance      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  731

    17.13  einvalidargument          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  731



                                                                 39

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           17.13.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  731


18   Reference for unit 'matrix'                                                                                        732

    18.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  732

    18.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  733

           18.2.1    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  733

    18.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  735

           18.3.1    operator *(Tmatrix2_double, double):  Tmatrix2_double                           .  .  .  .  .  .  .  .  735

           18.3.2    operator *(Tmatrix2_double, Tmatrix2_double):  Tmatrix2_double                                .  .  735

           18.3.3    operator *(Tmatrix2_double, Tvector2_double):  Tvector2_double                              .  .  .  736

           18.3.4    operator *(Tmatrix2_extended, extended):  Tmatrix2_extended                              .  .  .  .  736

           18.3.5    operator *(Tmatrix2_extended, Tmatrix2_extended):  Tmatrix2_extended                                 736

           18.3.6    operator *(Tmatrix2_extended, Tvector2_extended):  Tvector2_extended                                736

           18.3.7    operator *(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  737

           18.3.8    operator *(Tmatrix2_single, Tmatrix2_single):  Tmatrix2_single                           .  .  .  .  737

           18.3.9    operator *(Tmatrix2_single, Tvector2_single):  Tvector2_single                         .  .  .  .  .  737

           18.3.10   operator *(Tmatrix3_double, double):  Tmatrix3_double                           .  .  .  .  .  .  .  .  737

           18.3.11   operator *(Tmatrix3_double, Tmatrix3_double):  Tmatrix3_double                                .  .  738

           18.3.12   operator *(Tmatrix3_double, Tvector3_double):  Tvector3_double                              .  .  .  738

           18.3.13   operator *(Tmatrix3_extended, extended):  Tmatrix3_extended                              .  .  .  .  738

           18.3.14   operator *(Tmatrix3_extended, Tmatrix3_extended):  Tmatrix3_extended                                 739

           18.3.15   operator *(Tmatrix3_extended, Tvector3_extended):  Tvector3_extended                                739

           18.3.16   operator *(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  739

           18.3.17   operator *(Tmatrix3_single, Tmatrix3_single):  Tmatrix3_single                           .  .  .  .  739

           18.3.18   operator *(Tmatrix3_single, Tvector3_single):  Tvector3_single                         .  .  .  .  .  740

           18.3.19   operator *(Tmatrix4_double, double):  Tmatrix4_double                           .  .  .  .  .  .  .  .  740

           18.3.20   operator *(Tmatrix4_double, Tmatrix4_double):  Tmatrix4_double                                .  .  740

           18.3.21   operator *(Tmatrix4_double, Tvector4_double):  Tvector4_double                              .  .  .  740

           18.3.22   operator *(Tmatrix4_extended, extended):  Tmatrix4_extended                              .  .  .  .  741

           18.3.23   operator *(Tmatrix4_extended, Tmatrix4_extended):  Tmatrix4_extended                                 741

           18.3.24   operator *(Tmatrix4_extended, Tvector4_extended):  Tvector4_extended                                741

           18.3.25   operator *(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  742

           18.3.26   operator *(Tmatrix4_single, Tmatrix4_single):  Tmatrix4_single                           .  .  .  .  742

           18.3.27   operator *(Tmatrix4_single, Tvector4_single):  Tvector4_single                         .  .  .  .  .  742

           18.3.28   operator *(Tvector2_double, double):  Tvector2_double                        .  .  .  .  .  .  .  .  .  742

           18.3.29   operator *(Tvector2_double, Tvector2_double):  Tvector2_double                              .  .  .  743

           18.3.30   operator *(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  .  .  743

           18.3.31   operator *(Tvector2_extended, Tvector2_extended):  Tvector2_extended                                743

           18.3.32   operator *(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  743

           18.3.33   operator *(Tvector2_single, Tvector2_single):  Tvector2_single                         .  .  .  .  .  744
                                                                 40

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.34   operator *(Tvector3_double, double):  Tvector3_double                        .  .  .  .  .  .  .  .  .  744

           18.3.35   operator *(Tvector3_double, Tvector3_double):  Tvector3_double                              .  .  .  744

           18.3.36   operator *(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  .  .  744

           18.3.37   operator *(Tvector3_extended, Tvector3_extended):  Tvector3_extended                                745

           18.3.38   operator *(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  745

           18.3.39   operator *(Tvector3_single, Tvector3_single):  Tvector3_single                         .  .  .  .  .  745

           18.3.40   operator *(Tvector4_double, double):  Tvector4_double                        .  .  .  .  .  .  .  .  .  745

           18.3.41   operator *(Tvector4_double, Tvector4_double):  Tvector4_double                              .  .  .  746

           18.3.42   operator *(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  .  .  746

           18.3.43   operator *(Tvector4_extended, Tvector4_extended):  Tvector4_extended                                746

           18.3.44   operator *(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  746

           18.3.45   operator *(Tvector4_single, Tvector4_single):  Tvector4_single                         .  .  .  .  .  747

           18.3.46   operator **(Tvector2_double, Tvector2_double):  double                          .  .  .  .  .  .  .  .  747

           18.3.47   operator **(Tvector2_extended, Tvector2_extended):  extended                             .  .  .  .  747

           18.3.48   operator **(Tvector2_single, Tvector2_single):  single                     .  .  .  .  .  .  .  .  .  .  747

           18.3.49   operator **(Tvector3_double, Tvector3_double):  double                          .  .  .  .  .  .  .  .  748

           18.3.50   operator **(Tvector3_extended, Tvector3_extended):  extended                             .  .  .  .  748

           18.3.51   operator **(Tvector3_single, Tvector3_single):  single                     .  .  .  .  .  .  .  .  .  .  748

           18.3.52   operator **(Tvector4_double, Tvector4_double):  double                          .  .  .  .  .  .  .  .  748

           18.3.53   operator **(Tvector4_extended, Tvector4_extended):  extended                             .  .  .  .  749

           18.3.54   operator **(Tvector4_single, Tvector4_single):  single                     .  .  .  .  .  .  .  .  .  .  749

           18.3.55   operator +(Tmatrix2_double, double):  Tmatrix2_double                           .  .  .  .  .  .  .  .  749

           18.3.56   operator +(Tmatrix2_double, Tmatrix2_double):  Tmatrix2_double                                .  .  749

           18.3.57   operator +(Tmatrix2_extended, extended):  Tmatrix2_extended                              .  .  .  .  750

           18.3.58   operator +(Tmatrix2_extended, Tmatrix2_extended):  Tmatrix2_extended                                  750

           18.3.59   operator +(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  750

           18.3.60   operator +(Tmatrix2_single, Tmatrix2_single):  Tmatrix2_single                           .  .  .  .  750

           18.3.61   operator +(Tmatrix3_double, double):  Tmatrix3_double                           .  .  .  .  .  .  .  .  751

           18.3.62   operator +(Tmatrix3_double, Tmatrix3_double):  Tmatrix3_double                                .  .  751

           18.3.63   operator +(Tmatrix3_extended, extended):  Tmatrix3_extended                              .  .  .  .  751

           18.3.64   operator +(Tmatrix3_extended, Tmatrix3_extended):  Tmatrix3_extended                                  751

           18.3.65   operator +(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  752

           18.3.66   operator +(Tmatrix3_single, Tmatrix3_single):  Tmatrix3_single                           .  .  .  .  752

           18.3.67   operator +(Tmatrix4_double, double):  Tmatrix4_double                           .  .  .  .  .  .  .  .  752

           18.3.68   operator +(Tmatrix4_double, Tmatrix4_double):  Tmatrix4_double                                .  .  752

           18.3.69   operator +(Tmatrix4_extended, extended):  Tmatrix4_extended                              .  .  .  .  753

           18.3.70   operator +(Tmatrix4_extended, Tmatrix4_extended):  Tmatrix4_extended                                  753

           18.3.71   operator +(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  753

           18.3.72   operator +(Tmatrix4_single, Tmatrix4_single):  Tmatrix4_single                           .  .  .  .  753

           18.3.73   operator +(Tvector2_double, double):  Tvector2_double                        .  .  .  .  .  .  .  .  .  754



                                                                 41

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.74   operator +(Tvector2_double, Tvector2_double):  Tvector2_double                              .  .  .  754

           18.3.75   operator +(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  .  .  754

           18.3.76   operator +(Tvector2_extended, Tvector2_extended):  Tvector2_extended                                754

           18.3.77   operator +(Tvector2_single, single):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  755

           18.3.78   operator +(Tvector2_single, Tvector2_single):  Tvector2_single                         .  .  .  .  .  755

           18.3.79   operator +(Tvector3_double, double):  Tvector3_double                        .  .  .  .  .  .  .  .  .  755

           18.3.80   operator +(Tvector3_double, Tvector3_double):  Tvector3_double                              .  .  .  755

           18.3.81   operator +(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  .  .  756

           18.3.82   operator +(Tvector3_extended, Tvector3_extended):  Tvector3_extended                                756

           18.3.83   operator +(Tvector3_single, single):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  756

           18.3.84   operator +(Tvector3_single, Tvector3_single):  Tvector3_single                         .  .  .  .  .  756

           18.3.85   operator +(Tvector4_double, double):  Tvector4_double                        .  .  .  .  .  .  .  .  .  757

           18.3.86   operator +(Tvector4_double, Tvector4_double):  Tvector4_double                              .  .  .  757

           18.3.87   operator +(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  .  .  757

           18.3.88   operator +(Tvector4_extended, Tvector4_extended):  Tvector4_extended                                757

           18.3.89   operator +(Tvector4_single, single):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  758

           18.3.90   operator +(Tvector4_single, Tvector4_single):  Tvector4_single                         .  .  .  .  .  758

           18.3.91   operator -(Tmatrix2_double):  Tmatrix2_double                      .  .  .  .  .  .  .  .  .  .  .  .  .  758

           18.3.92   operator -(Tmatrix2_double, double):  Tmatrix2_double                           .  .  .  .  .  .  .  .  758

           18.3.93   operator -(Tmatrix2_double, Tmatrix2_double):  Tmatrix2_double                              .  .  .  759

           18.3.94   operator -(Tmatrix2_extended):  Tmatrix2_extended                          .  .  .  .  .  .  .  .  .  .  759

           18.3.95   operator -(Tmatrix2_extended, extended):  Tmatrix2_extended                              .  .  .  .  759

           18.3.96   operator -(Tmatrix2_extended, Tmatrix2_extended):  Tmatrix2_extended                                759

           18.3.97   operator -(Tmatrix2_single):  Tmatrix2_single                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  760

           18.3.98   operator -(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  760

           18.3.99   operator -(Tmatrix2_single, Tmatrix2_single):  Tmatrix2_single                           .  .  .  .  760

           18.3.100  operator -(Tmatrix3_double):  Tmatrix3_double                      .  .  .  .  .  .  .  .  .  .  .  .  .  760

           18.3.101  operator -(Tmatrix3_double, double):  Tmatrix3_double                           .  .  .  .  .  .  .  .  761

           18.3.102  operator -(Tmatrix3_double, Tmatrix3_double):  Tmatrix3_double                              .  .  .  761

           18.3.103  operator -(Tmatrix3_extended):  Tmatrix3_extended                          .  .  .  .  .  .  .  .  .  .  761

           18.3.104  operator -(Tmatrix3_extended, extended):  Tmatrix3_extended                              .  .  .  .  761

           18.3.105  operator -(Tmatrix3_extended, Tmatrix3_extended):  Tmatrix3_extended                                762

           18.3.106  operator -(Tmatrix3_single):  Tmatrix3_single                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  762

           18.3.107  operator -(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  762

           18.3.108  operator -(Tmatrix3_single, Tmatrix3_single):  Tmatrix3_single                           .  .  .  .  762

           18.3.109  operator -(Tmatrix4_double):  Tmatrix4_double                      .  .  .  .  .  .  .  .  .  .  .  .  .  763

           18.3.110  operator -(Tmatrix4_double, double):  Tmatrix4_double                           .  .  .  .  .  .  .  .  763

           18.3.111  operator -(Tmatrix4_double, Tmatrix4_double):  Tmatrix4_double                              .  .  .  763

           18.3.112  operator -(Tmatrix4_extended):  Tmatrix4_extended                          .  .  .  .  .  .  .  .  .  .  763

           18.3.113  operator -(Tmatrix4_extended, extended):  Tmatrix4_extended                              .  .  .  .  764



                                                                 42

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.114  operator -(Tmatrix4_extended, Tmatrix4_extended):  Tmatrix4_extended                                764

           18.3.115  operator -(Tmatrix4_single):  Tmatrix4_single                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  764

           18.3.116  operator -(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  764

           18.3.117  operator -(Tmatrix4_single, Tmatrix4_single):  Tmatrix4_single                           .  .  .  .  765

           18.3.118  operator -(Tvector2_double):  Tvector2_double                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  765

           18.3.119  operator -(Tvector2_double, double):  Tvector2_double                        .  .  .  .  .  .  .  .  .  765

           18.3.120  operator -(Tvector2_double, Tvector2_double):  Tvector2_double                           .  .  .  .  765

           18.3.121  operator -(Tvector2_extended):  Tvector2_extended                       .  .  .  .  .  .  .  .  .  .  .  766

           18.3.122  operator -(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  .  .  766

           18.3.123  operator -(Tvector2_extended, Tvector2_extended):  Tvector2_extended                                766

           18.3.124  operator -(Tvector2_single):  Tvector2_single                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  766

           18.3.125  operator -(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  767

           18.3.126  operator -(Tvector2_single, Tvector2_single):  Tvector2_single                         .  .  .  .  .  767

           18.3.127  operator -(Tvector3_double):  Tvector3_double                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  767

           18.3.128  operator -(Tvector3_double, double):  Tvector3_double                        .  .  .  .  .  .  .  .  .  767

           18.3.129  operator -(Tvector3_double, Tvector3_double):  Tvector3_double                           .  .  .  .  768

           18.3.130  operator -(Tvector3_extended):  Tvector3_extended                       .  .  .  .  .  .  .  .  .  .  .  768

           18.3.131  operator -(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  .  .  768

           18.3.132  operator -(Tvector3_extended, Tvector3_extended):  Tvector3_extended                                768

           18.3.133  operator -(Tvector3_single):  Tvector3_single                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  769

           18.3.134  operator -(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  769

           18.3.135  operator -(Tvector3_single, Tvector3_single):  Tvector3_single                         .  .  .  .  .  769

           18.3.136  operator -(Tvector4_double):  Tvector4_double                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  769

           18.3.137  operator -(Tvector4_double, double):  Tvector4_double                        .  .  .  .  .  .  .  .  .  770

           18.3.138  operator -(Tvector4_double, Tvector4_double):  Tvector4_double                           .  .  .  .  770

           18.3.139  operator -(Tvector4_extended):  Tvector4_extended                       .  .  .  .  .  .  .  .  .  .  .  770

           18.3.140  operator -(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  .  .  770

           18.3.141  operator -(Tvector4_extended, Tvector4_extended):  Tvector4_extended                                771

           18.3.142  operator -(Tvector4_single):  Tvector4_single                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  771

           18.3.143  operator -(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  771

           18.3.144  operator -(Tvector4_single, Tvector4_single):  Tvector4_single                         .  .  .  .  .  771

           18.3.145  operator /(Tmatrix2_double, double):  Tmatrix2_double                           .  .  .  .  .  .  .  .  772

           18.3.146  operator /(Tmatrix2_extended, extended):  Tmatrix2_extended                              .  .  .  .  772

           18.3.147  operator /(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  772

           18.3.148  operator /(Tmatrix3_double, double):  Tmatrix3_double                           .  .  .  .  .  .  .  .  772

           18.3.149  operator /(Tmatrix3_extended, extended):  Tmatrix3_extended                              .  .  .  .  773

           18.3.150  operator /(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  773

           18.3.151  operator /(Tmatrix4_double, double):  Tmatrix4_double                           .  .  .  .  .  .  .  .  773

           18.3.152  operator /(Tmatrix4_extended, extended):  Tmatrix4_extended                              .  .  .  .  773

           18.3.153  operator /(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  774



                                                                 43

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.154  operator /(Tvector2_double, double):  Tvector2_double                        .  .  .  .  .  .  .  .  .  774

           18.3.155  operator /(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  .  .  774

           18.3.156  operator /(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  774

           18.3.157  operator /(Tvector3_double, double):  Tvector3_double                        .  .  .  .  .  .  .  .  .  775

           18.3.158  operator /(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  .  .  775

           18.3.159  operator /(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  775

           18.3.160  operator /(Tvector4_double, double):  Tvector4_double                        .  .  .  .  .  .  .  .  .  775

           18.3.161  operator /(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  .  .  776

           18.3.162  operator /(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  776

           18.3.163  operator :=(Tmatrix2_double):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  .  .  776

           18.3.164  operator :=(Tmatrix2_double):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  776

           18.3.165  operator :=(Tmatrix2_double):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  .  .  777

           18.3.166  operator :=(Tmatrix2_double):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  .  .  777

           18.3.167  operator :=(Tmatrix2_double):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  777

           18.3.168  operator :=(Tmatrix2_double):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  .  .  777

           18.3.169  operator :=(Tmatrix2_double):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  .  .  778

           18.3.170  operator :=(Tmatrix2_double):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  778

           18.3.171  operator :=(Tmatrix2_extended):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  .  778

           18.3.172  operator :=(Tmatrix2_extended):  Tmatrix2_single                        .  .  .  .  .  .  .  .  .  .  .  778

           18.3.173  operator :=(Tmatrix2_extended):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  .  779

           18.3.174  operator :=(Tmatrix2_extended):  Tmatrix3_extended                           .  .  .  .  .  .  .  .  .  779

           18.3.175  operator :=(Tmatrix2_extended):  Tmatrix3_single                        .  .  .  .  .  .  .  .  .  .  .  779

           18.3.176  operator :=(Tmatrix2_extended):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  .  779

           18.3.177  operator :=(Tmatrix2_extended):  Tmatrix4_extended                           .  .  .  .  .  .  .  .  .  780

           18.3.178  operator :=(Tmatrix2_extended):  Tmatrix4_single                        .  .  .  .  .  .  .  .  .  .  .  780

           18.3.179  operator :=(Tmatrix2_single):  Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  780

           18.3.180  operator :=(Tmatrix2_single):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  .  .  780

           18.3.181  operator :=(Tmatrix2_single):  Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  781

           18.3.182  operator :=(Tmatrix2_single):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  .  .  781

           18.3.183  operator :=(Tmatrix2_single):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  781

           18.3.184  operator :=(Tmatrix2_single):  Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  781

           18.3.185  operator :=(Tmatrix2_single):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  .  .  782

           18.3.186  operator :=(Tmatrix2_single):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  782

           18.3.187  operator :=(Tmatrix3_double):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  .  .  782

           18.3.188  operator :=(Tmatrix3_double):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  .  .  782

           18.3.189  operator :=(Tmatrix3_double):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  783

           18.3.190  operator :=(Tmatrix3_double):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  .  .  783

           18.3.191  operator :=(Tmatrix3_double):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  783

           18.3.192  operator :=(Tmatrix3_double):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  .  .  783

           18.3.193  operator :=(Tmatrix3_double):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  .  .  784



                                                                 44

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.194  operator :=(Tmatrix3_double):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  784

           18.3.195  operator :=(Tmatrix3_extended):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  .  784

           18.3.196  operator :=(Tmatrix3_extended):  Tmatrix2_extended                           .  .  .  .  .  .  .  .  .  784

           18.3.197  operator :=(Tmatrix3_extended):  Tmatrix2_single                        .  .  .  .  .  .  .  .  .  .  .  785

           18.3.198  operator :=(Tmatrix3_extended):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  .  785

           18.3.199  operator :=(Tmatrix3_extended):  Tmatrix3_single                        .  .  .  .  .  .  .  .  .  .  .  785

           18.3.200  operator :=(Tmatrix3_extended):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  .  785

           18.3.201  operator :=(Tmatrix3_extended):  Tmatrix4_extended                           .  .  .  .  .  .  .  .  .  786

           18.3.202  operator :=(Tmatrix3_extended):  Tmatrix4_single                        .  .  .  .  .  .  .  .  .  .  .  786

           18.3.203  operator :=(Tmatrix3_single):  Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  786

           18.3.204  operator :=(Tmatrix3_single):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  .  .  786

           18.3.205  operator :=(Tmatrix3_single):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  787

           18.3.206  operator :=(Tmatrix3_single):  Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  787

           18.3.207  operator :=(Tmatrix3_single):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  .  .  787

           18.3.208  operator :=(Tmatrix3_single):  Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  787

           18.3.209  operator :=(Tmatrix3_single):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  .  .  788

           18.3.210  operator :=(Tmatrix3_single):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  788

           18.3.211  operator :=(Tmatrix4_double):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  .  .  788

           18.3.212  operator :=(Tmatrix4_double):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  .  .  788

           18.3.213  operator :=(Tmatrix4_double):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  789

           18.3.214  operator :=(Tmatrix4_double):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  .  .  789

           18.3.215  operator :=(Tmatrix4_double):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  .  .  789

           18.3.216  operator :=(Tmatrix4_double):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  789

           18.3.217  operator :=(Tmatrix4_double):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  .  .  790

           18.3.218  operator :=(Tmatrix4_double):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  790

           18.3.219  operator :=(Tmatrix4_extended):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  .  790

           18.3.220  operator :=(Tmatrix4_extended):  Tmatrix2_extended                           .  .  .  .  .  .  .  .  .  790

           18.3.221  operator :=(Tmatrix4_extended):  Tmatrix2_single                        .  .  .  .  .  .  .  .  .  .  .  791

           18.3.222  operator :=(Tmatrix4_extended):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  .  791

           18.3.223  operator :=(Tmatrix4_extended):  Tmatrix3_extended                           .  .  .  .  .  .  .  .  .  791

           18.3.224  operator :=(Tmatrix4_extended):  Tmatrix3_single                        .  .  .  .  .  .  .  .  .  .  .  791

           18.3.225  operator :=(Tmatrix4_extended):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  .  792

           18.3.226  operator :=(Tmatrix4_extended):  Tmatrix4_single                        .  .  .  .  .  .  .  .  .  .  .  792

           18.3.227  operator :=(Tmatrix4_single):  Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  792

           18.3.228  operator :=(Tmatrix4_single):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  .  .  792

           18.3.229  operator :=(Tmatrix4_single):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  793

           18.3.230  operator :=(Tmatrix4_single):  Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  793

           18.3.231  operator :=(Tmatrix4_single):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  .  .  793

           18.3.232  operator :=(Tmatrix4_single):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  793

           18.3.233  operator :=(Tmatrix4_single):  Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  794



                                                                 45

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.234  operator :=(Tmatrix4_single):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  .  .  794

           18.3.235  operator :=(Tvector2_double):  Tvector2_extended                        .  .  .  .  .  .  .  .  .  .  .  794

           18.3.236  operator :=(Tvector2_double):  Tvector2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  794

           18.3.237  operator :=(Tvector2_double):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  795

           18.3.238  operator :=(Tvector2_double):  Tvector3_extended                        .  .  .  .  .  .  .  .  .  .  .  795

           18.3.239  operator :=(Tvector2_double):  Tvector3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  795

           18.3.240  operator :=(Tvector2_double):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  795

           18.3.241  operator :=(Tvector2_double):  Tvector4_extended                        .  .  .  .  .  .  .  .  .  .  .  796

           18.3.242  operator :=(Tvector2_double):  Tvector4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  796

           18.3.243  operator :=(Tvector2_extended):  Tvector2_double                        .  .  .  .  .  .  .  .  .  .  .  796

           18.3.244  operator :=(Tvector2_extended):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  .  .  796

           18.3.245  operator :=(Tvector2_extended):  Tvector3_double                        .  .  .  .  .  .  .  .  .  .  .  797

           18.3.246  operator :=(Tvector2_extended):  Tvector3_extended                         .  .  .  .  .  .  .  .  .  .  797

           18.3.247  operator :=(Tvector2_extended):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  .  .  797

           18.3.248  operator :=(Tvector2_extended):  Tvector4_double                        .  .  .  .  .  .  .  .  .  .  .  797

           18.3.249  operator :=(Tvector2_extended):  Tvector4_extended                         .  .  .  .  .  .  .  .  .  .  798

           18.3.250  operator :=(Tvector2_extended):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  .  .  798

           18.3.251  operator :=(Tvector2_single):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  798

           18.3.252  operator :=(Tvector2_single):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  798

           18.3.253  operator :=(Tvector2_single):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  799

           18.3.254  operator :=(Tvector2_single):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  799

           18.3.255  operator :=(Tvector2_single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  799

           18.3.256  operator :=(Tvector2_single):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  799

           18.3.257  operator :=(Tvector2_single):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  800

           18.3.258  operator :=(Tvector2_single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  800

           18.3.259  operator :=(Tvector3_double):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  800

           18.3.260  operator :=(Tvector3_double):  Tvector2_extended                        .  .  .  .  .  .  .  .  .  .  .  800

           18.3.261  operator :=(Tvector3_double):  Tvector2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  801

           18.3.262  operator :=(Tvector3_double):  Tvector3_extended                        .  .  .  .  .  .  .  .  .  .  .  801

           18.3.263  operator :=(Tvector3_double):  Tvector3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  801

           18.3.264  operator :=(Tvector3_double):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  801

           18.3.265  operator :=(Tvector3_double):  Tvector4_extended                        .  .  .  .  .  .  .  .  .  .  .  802

           18.3.266  operator :=(Tvector3_double):  Tvector4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  802

           18.3.267  operator :=(Tvector3_extended):  Tvector2_double                        .  .  .  .  .  .  .  .  .  .  .  802

           18.3.268  operator :=(Tvector3_extended):  Tvector2_extended                         .  .  .  .  .  .  .  .  .  .  802

           18.3.269  operator :=(Tvector3_extended):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  .  .  803

           18.3.270  operator :=(Tvector3_extended):  Tvector3_double                        .  .  .  .  .  .  .  .  .  .  .  803

           18.3.271  operator :=(Tvector3_extended):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  .  .  803

           18.3.272  operator :=(Tvector3_extended):  Tvector4_double                        .  .  .  .  .  .  .  .  .  .  .  803

           18.3.273  operator :=(Tvector3_extended):  Tvector4_extended                         .  .  .  .  .  .  .  .  .  .  804



                                                                 46

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.3.274  operator :=(Tvector3_extended):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  .  .  804

           18.3.275  operator :=(Tvector3_single):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  804

           18.3.276  operator :=(Tvector3_single):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  804

           18.3.277  operator :=(Tvector3_single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  805

           18.3.278  operator :=(Tvector3_single):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  805

           18.3.279  operator :=(Tvector3_single):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  805

           18.3.280  operator :=(Tvector3_single):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  805

           18.3.281  operator :=(Tvector3_single):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  806

           18.3.282  operator :=(Tvector3_single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  806

           18.3.283  operator :=(Tvector4_double):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  806

           18.3.284  operator :=(Tvector4_double):  Tvector2_extended                        .  .  .  .  .  .  .  .  .  .  .  806

           18.3.285  operator :=(Tvector4_double):  Tvector2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  807

           18.3.286  operator :=(Tvector4_double):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  807

           18.3.287  operator :=(Tvector4_double):  Tvector3_extended                        .  .  .  .  .  .  .  .  .  .  .  807

           18.3.288  operator :=(Tvector4_double):  Tvector3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  807

           18.3.289  operator :=(Tvector4_double):  Tvector4_extended                        .  .  .  .  .  .  .  .  .  .  .  808

           18.3.290  operator :=(Tvector4_double):  Tvector4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  808

           18.3.291  operator :=(Tvector4_extended):  Tvector2_double                        .  .  .  .  .  .  .  .  .  .  .  808

           18.3.292  operator :=(Tvector4_extended):  Tvector2_extended                         .  .  .  .  .  .  .  .  .  .  808

           18.3.293  operator :=(Tvector4_extended):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  .  .  809

           18.3.294  operator :=(Tvector4_extended):  Tvector3_double                        .  .  .  .  .  .  .  .  .  .  .  809

           18.3.295  operator :=(Tvector4_extended):  Tvector3_extended                         .  .  .  .  .  .  .  .  .  .  809

           18.3.296  operator :=(Tvector4_extended):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  .  .  809

           18.3.297  operator :=(Tvector4_extended):  Tvector4_double                        .  .  .  .  .  .  .  .  .  .  .  810

           18.3.298  operator :=(Tvector4_extended):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  .  .  810

           18.3.299  operator :=(Tvector4_single):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  810

           18.3.300  operator :=(Tvector4_single):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  810

           18.3.301  operator :=(Tvector4_single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  811

           18.3.302  operator :=(Tvector4_single):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  811

           18.3.303  operator :=(Tvector4_single):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  811

           18.3.304  operator :=(Tvector4_single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  811

           18.3.305  operator :=(Tvector4_single):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  812

           18.3.306  operator :=(Tvector4_single):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  812

           18.3.307  operator ><(Tvector3_double, Tvector3_double):  Tvector3_double                             .  .  .  812

           18.3.308  operator ><(Tvector3_extended, Tvector3_extended):  Tvector3_extended                               812

           18.3.309  operator ><(Tvector3_single, Tvector3_single):  Tvector3_single                        .  .  .  .  .  813

    18.4   Tmatrix2_double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  813

           18.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  813

           18.4.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  813

           18.4.3    Tmatrix2_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  813



                                                                 47

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.4.4    Tmatrix2_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  814

           18.4.5    Tmatrix2_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  814

           18.4.6    Tmatrix2_double.get_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  814

           18.4.7    Tmatrix2_double.get_row               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  814

           18.4.8    Tmatrix2_double.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  814

           18.4.9    Tmatrix2_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  814

           18.4.10   Tmatrix2_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  815

           18.4.11   Tmatrix2_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  815

           18.4.12   Tmatrix2_double.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  815

    18.5   Tmatrix2_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  815

           18.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  815

           18.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  815

           18.5.3    Tmatrix2_extended.init_zero              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  816

           18.5.4    Tmatrix2_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 816

           18.5.5    Tmatrix2_extended.init              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  816

           18.5.6    Tmatrix2_extended.get_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 816

           18.5.7    Tmatrix2_extended.get_row                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  816

           18.5.8    Tmatrix2_extended.set_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 816

           18.5.9    Tmatrix2_extended.set_row                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  817

           18.5.10   Tmatrix2_extended.determinant                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 817

           18.5.11   Tmatrix2_extended.inverse                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  817

           18.5.12   Tmatrix2_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  817

    18.6   Tmatrix2_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  817

           18.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  817

           18.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  818

           18.6.3    Tmatrix2_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  818

           18.6.4    Tmatrix2_single.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  818

           18.6.5    Tmatrix2_single.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  818

           18.6.6    Tmatrix2_single.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  818

           18.6.7    Tmatrix2_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  819

           18.6.8    Tmatrix2_single.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  819

           18.6.9    Tmatrix2_single.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  819

           18.6.10   Tmatrix2_single.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  819

           18.6.11   Tmatrix2_single.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  819

           18.6.12   Tmatrix2_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  819

    18.7   Tmatrix3_double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  820

           18.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  820

           18.7.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  820

           18.7.3    Tmatrix3_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  820

           18.7.4    Tmatrix3_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  820



                                                                 48

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.7.5    Tmatrix3_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  820

           18.7.6    Tmatrix3_double.get_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  821

           18.7.7    Tmatrix3_double.get_row               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  821

           18.7.8    Tmatrix3_double.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  821

           18.7.9    Tmatrix3_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  821

           18.7.10   Tmatrix3_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  821

           18.7.11   Tmatrix3_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  821

           18.7.12   Tmatrix3_double.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  822

    18.8   Tmatrix3_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  822

           18.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  822

           18.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  822

           18.8.3    Tmatrix3_extended.init_zero              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  822

           18.8.4    Tmatrix3_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 822

           18.8.5    Tmatrix3_extended.init              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  823

           18.8.6    Tmatrix3_extended.get_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 823

           18.8.7    Tmatrix3_extended.get_row                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  823

           18.8.8    Tmatrix3_extended.set_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 823

           18.8.9    Tmatrix3_extended.set_row                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  823

           18.8.10   Tmatrix3_extended.determinant                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 824

           18.8.11   Tmatrix3_extended.inverse                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  824

           18.8.12   Tmatrix3_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  824

    18.9   Tmatrix3_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  824

           18.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  824

           18.9.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  824

           18.9.3    Tmatrix3_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  825

           18.9.4    Tmatrix3_single.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  825

           18.9.5    Tmatrix3_single.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  825

           18.9.6    Tmatrix3_single.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  825

           18.9.7    Tmatrix3_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  825

           18.9.8    Tmatrix3_single.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  825

           18.9.9    Tmatrix3_single.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  826

           18.9.10   Tmatrix3_single.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  826

           18.9.11   Tmatrix3_single.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  826

           18.9.12   Tmatrix3_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  826

    18.10  Tmatrix4_double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  826

           18.10.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  826

           18.10.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  827

           18.10.3   Tmatrix4_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  827

           18.10.4   Tmatrix4_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  827

           18.10.5   Tmatrix4_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  827



                                                                 49

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.10.6   Tmatrix4_double.get_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  827

           18.10.7   Tmatrix4_double.get_row               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  828

           18.10.8   Tmatrix4_double.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  828

           18.10.9   Tmatrix4_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  828

           18.10.10  Tmatrix4_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  828

           18.10.11  Tmatrix4_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  828

           18.10.12  Tmatrix4_double.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  829

    18.11  Tmatrix4_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  829

           18.11.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  829

           18.11.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  829

           18.11.3   Tmatrix4_extended.init_zero              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  829

           18.11.4   Tmatrix4_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 829

           18.11.5   Tmatrix4_extended.init              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  830

           18.11.6   Tmatrix4_extended.get_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 830

           18.11.7   Tmatrix4_extended.get_row                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  830

           18.11.8   Tmatrix4_extended.set_column                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 830

           18.11.9   Tmatrix4_extended.set_row                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  830

           18.11.10  Tmatrix4_extended.determinant                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 831

           18.11.11  Tmatrix4_extended.inverse                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  831

           18.11.12  Tmatrix4_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  831

    18.12  Tmatrix4_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  831

           18.12.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  831

           18.12.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  831

           18.12.3   Tmatrix4_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  832

           18.12.4   Tmatrix4_single.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  832

           18.12.5   Tmatrix4_single.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  832

           18.12.6   Tmatrix4_single.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  832

           18.12.7   Tmatrix4_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  832

           18.12.8   Tmatrix4_single.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  833

           18.12.9   Tmatrix4_single.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  833

           18.12.10  Tmatrix4_single.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  833

           18.12.11  Tmatrix4_single.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  833

           18.12.12  Tmatrix4_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  833

    18.13  Tvector2_double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  834

           18.13.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  834

           18.13.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  834

           18.13.3   Tvector2_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  834

           18.13.4   Tvector2_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  834

           18.13.5   Tvector2_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  834

           18.13.6   Tvector2_double.length              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  834



                                                                 50

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.13.7   Tvector2_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 835

    18.14  Tvector2_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  835

           18.14.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  835

           18.14.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  835

           18.14.3   Tvector2_extended.init_zero              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  835

           18.14.4   Tvector2_extended.init_one               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  835

           18.14.5   Tvector2_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  835

           18.14.6   Tvector2_extended.length              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  836

           18.14.7   Tvector2_extended.squared_length                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *836

    18.15  Tvector2_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  836

           18.15.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  836

           18.15.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  836

           18.15.3   Tvector2_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  836

           18.15.4   Tvector2_single.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  836

           18.15.5   Tvector2_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  837

           18.15.6   Tvector2_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  837

           18.15.7   Tvector2_single.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 837

    18.16  Tvector3_double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  837

           18.16.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  837

           18.16.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  837

           18.16.3   Tvector3_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  837

           18.16.4   Tvector3_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  838

           18.16.5   Tvector3_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  838

           18.16.6   Tvector3_double.length              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  838

           18.16.7   Tvector3_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 838

    18.17  Tvector3_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  838

           18.17.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  838

           18.17.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  838

           18.17.3   Tvector3_extended.init_zero              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  839

           18.17.4   Tvector3_extended.init_one               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  839

           18.17.5   Tvector3_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  839

           18.17.6   Tvector3_extended.length              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  839

           18.17.7   Tvector3_extended.squared_length                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *839

    18.18  Tvector3_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  839

           18.18.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  839

           18.18.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  840

           18.18.3   Tvector3_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  840

           18.18.4   Tvector3_single.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  840

           18.18.5   Tvector3_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  840

           18.18.6   Tvector3_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  840



                                                                 51

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.18.7   Tvector3_single.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 840

    18.19  Tvector4_double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  841

           18.19.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  841

           18.19.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  841

           18.19.3   Tvector4_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  841

           18.19.4   Tvector4_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  841

           18.19.5   Tvector4_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  841

           18.19.6   Tvector4_double.length              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  841

           18.19.7   Tvector4_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 842

    18.20  Tvector4_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  842

           18.20.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  842

           18.20.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  842

           18.20.3   Tvector4_extended.init_zero              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  842

           18.20.4   Tvector4_extended.init_one               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  842

           18.20.5   Tvector4_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  842

           18.20.6   Tvector4_extended.length              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  843

           18.20.7   Tvector4_extended.squared_length                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *843

    18.21  Tvector4_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  843

           18.21.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  843

           18.21.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  843

           18.21.3   Tvector4_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  843

           18.21.4   Tvector4_single.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  843

           18.21.5   Tvector4_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  844

           18.21.6   Tvector4_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  844

           18.21.7   Tvector4_single.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 844


19   Reference for unit 'mmx'                                                                                           845

    19.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  845

    19.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  845

           19.2.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  845

           19.2.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  846

    19.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  847

           19.3.1    emms       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  847

           19.3.2    femms      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  847


20   Reference for unit 'Mouse'                                                                                         848

    20.1   Writing a custom mouse driver                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  848

    20.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  848

    20.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  848

           20.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  848

           20.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  849



                                                                 52

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           20.3.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  850

    20.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  850

           20.4.1    DetectMouse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  850

           20.4.2    DoneMouse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  851

           20.4.3    GetMouseButtons             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  851

           20.4.4    GetMouseDriver            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  852

           20.4.5    GetMouseEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  852

           20.4.6    GetMouseX          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  853

           20.4.7    GetMouseY          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  853

           20.4.8    HideMouse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  854

           20.4.9    InitMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  854

           20.4.10   PollMouseEvent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  855

           20.4.11   PutMouseEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  855

           20.4.12   SetMouseDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  855

           20.4.13   SetMouseXY           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  856

           20.4.14   ShowMouse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  856


21   Reference for unit 'Objects'                                                                                       858

    21.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  858

    21.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  858

           21.2.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  858

           21.2.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  860

           21.2.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  864

    21.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  864

           21.3.1    Abstract      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  864

           21.3.2    CallPointerConstructor              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  864

           21.3.3    CallPointerLocal          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  865

           21.3.4    CallPointerMethod           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  865

           21.3.5    CallPointerMethodLocal              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  865

           21.3.6    CallVoidConstructor            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  866

           21.3.7    CallVoidLocal        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  866

           21.3.8    CallVoidMethod            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  866

           21.3.9    CallVoidMethodLocal              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  867

           21.3.10   DisposeStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  867

           21.3.11   LongDiv       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  867

           21.3.12   LongMul         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  868

           21.3.13   NewStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  868

           21.3.14   RegisterObjects        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  868

           21.3.15   RegisterType         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  869

           21.3.16   SetStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  870
                                                                 53

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    21.4   TBufStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  871

           21.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  871

           21.4.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  871

           21.4.3    TBufStream.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  871

           21.4.4    TBufStream.Done             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  872

           21.4.5    TBufStream.Close            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  872

           21.4.6    TBufStream.Flush            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  872

           21.4.7    TBufStream.Truncate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  873

           21.4.8    TBufStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  873

           21.4.9    TBufStream.Open             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  874

           21.4.10   TBufStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  874

           21.4.11   TBufStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  874

    21.5   TCollection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  875

           21.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  875

           21.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  875

           21.5.3    TCollection.Init       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  875

           21.5.4    TCollection.Load          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  876

           21.5.5    TCollection.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  877

           21.5.6    TCollection.At         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  877

           21.5.7    TCollection.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  878

           21.5.8    TCollection.GetItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  879

           21.5.9    TCollection.LastThat             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  879

           21.5.10   TCollection.FirstThat            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  880

           21.5.11   TCollection.Pack          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  881

           21.5.12   TCollection.FreeAll         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  881

           21.5.13   TCollection.DeleteAll            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  882

           21.5.14   TCollection.Free          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  883

           21.5.15   TCollection.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  884

           21.5.16   TCollection.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  884

           21.5.17   TCollection.AtFree          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  885

           21.5.18   TCollection.FreeItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  885

           21.5.19   TCollection.AtDelete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  886

           21.5.20   TCollection.ForEach            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  886

           21.5.21   TCollection.SetLimit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  887

           21.5.22   TCollection.Error         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  888

           21.5.23   TCollection.AtPut           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  888

           21.5.24   TCollection.AtInsert           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  888

           21.5.25   TCollection.Store         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  889

           21.5.26   TCollection.PutItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  889

    21.6   TDosStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  890



                                                                 54

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           21.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  890

           21.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  890

           21.6.3    TDosStream.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  890

           21.6.4    TDosStream.Done             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  890

           21.6.5    TDosStream.Close            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  891

           21.6.6    TDosStream.Truncate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  891

           21.6.7    TDosStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  892

           21.6.8    TDosStream.Open             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  893

           21.6.9    TDosStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  893

           21.6.10   TDosStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  894

    21.7   TMemoryStream             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  894

           21.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  894

           21.7.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  894

           21.7.3    TMemoryStream.Init             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  894

           21.7.4    TMemoryStream.Done               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  895

           21.7.5    TMemoryStream.Truncate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  895

           21.7.6    TMemoryStream.Read               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  896

           21.7.7    TMemoryStream.Write                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  896

    21.8   TObject       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  896

           21.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  896

           21.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  897

           21.8.3    TObject.Init         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  897

           21.8.4    TObject.Free         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  897

           21.8.5    TObject.Is_Object           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  898

           21.8.6    TObject.Done           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  898

    21.9   TPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  898

           21.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  898

    21.10  TRect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  898

           21.10.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  898

           21.10.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  899

           21.10.3   TRect.Empty          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  899

           21.10.4   TRect.Equals         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  900

           21.10.5   TRect.Contains         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  900

           21.10.6   TRect.Copy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  900

           21.10.7   TRect.Union          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  901

           21.10.8   TRect.Intersect        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  902

           21.10.9   TRect.Move         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  902

           21.10.10  TRect.Grow         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  903

           21.10.11  TRect.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  904

    21.11  TResourceCollection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  904



                                                                 55

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           21.11.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  904

           21.11.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  905

           21.11.3   TResourceCollection.KeyOf                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  905

           21.11.4   TResourceCollection.GetItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  905

           21.11.5   TResourceCollection.FreeItem               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  905

           21.11.6   TResourceCollection.PutItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  906

    21.12  TResourceFile        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  906

           21.12.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  906

           21.12.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  906

           21.12.3   TResourceFile.Init          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  906

           21.12.4   TResourceFile.Done             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  907

           21.12.5   TResourceFile.Count            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  907

           21.12.6   TResourceFile.KeyAt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  907

           21.12.7   TResourceFile.Get           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  907

           21.12.8   TResourceFile.SwitchTo              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  908

           21.12.9   TResourceFile.Flush            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  908

           21.12.10  TResourceFile.Delete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  908

           21.12.11  TResourceFile.Put           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  908

    21.13  TSortedCollection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  909

           21.13.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  909

           21.13.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  909

           21.13.3   TSortedCollection.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  909

           21.13.4   TSortedCollection.Load              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  910

           21.13.5   TSortedCollection.KeyOf               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  910

           21.13.6   TSortedCollection.IndexOf                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  910

           21.13.7   TSortedCollection.Compare                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  911

           21.13.8   TSortedCollection.Search              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  911

           21.13.9   TSortedCollection.Insert            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  913

           21.13.10  TSortedCollection.Store             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  914

    21.14  TStrCollection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  914

           21.14.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  914

           21.14.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  914

           21.14.3   TStrCollection.Compare              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  914

           21.14.4   TStrCollection.GetItem              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  915

           21.14.5   TStrCollection.FreeItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  915

           21.14.6   TStrCollection.PutItem              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  916

    21.15  TStream       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  916

           21.15.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  916

           21.15.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  916

           21.15.3   TStream.Init         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  917



                                                                 56

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           21.15.4   TStream.Get          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  917

           21.15.5   TStream.StrRead           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  917

           21.15.6   TStream.GetPos            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  918

           21.15.7   TStream.GetSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  919

           21.15.8   TStream.ReadStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  919

           21.15.9   TStream.Open           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  920

           21.15.10  TStream.Close          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  920

           21.15.11  TStream.Reset          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  921

           21.15.12  TStream.Flush          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  921

           21.15.13  TStream.Truncate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  921

           21.15.14  TStream.Put          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  922

           21.15.15  TStream.StrWrite            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  922

           21.15.16  TStream.WriteStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  922

           21.15.17  TStream.Seek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  922

           21.15.18  TStream.Error          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  923

           21.15.19  TStream.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  923

           21.15.20  TStream.Write          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  924

           21.15.21  TStream.CopyFrom               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  924

    21.16  TStringCollection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  925

           21.16.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  925

           21.16.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  925

           21.16.3   TStringCollection.GetItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  925

           21.16.4   TStringCollection.Compare                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  925

           21.16.5   TStringCollection.FreeItem               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  926

           21.16.6   TStringCollection.PutItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  927

    21.17  TStringList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  927

           21.17.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  927

           21.17.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  927

           21.17.3   TStringList.Load          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  927

           21.17.4   TStringList.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  927

           21.17.5   TStringList.Get        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  928

    21.18  TStrListMaker           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  928

           21.18.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  928

           21.18.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  928

           21.18.3   TStrListMaker.Init          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  928

           21.18.4   TStrListMaker.Done             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  929

           21.18.5   TStrListMaker.Put           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  929

           21.18.6   TStrListMaker.Store            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  929

    21.19  TUnSortedStrCollection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  929

           21.19.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  929



                                                                 57

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           21.19.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  930

           21.19.3   TUnSortedStrCollection.Insert                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 930


22   Reference for unit 'objpas'                                                                                        931

    22.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  931

    22.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  931

           22.2.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  931

           22.2.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  931

           22.2.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  932

    22.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  933

           22.3.1    AssignFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  933

           22.3.2    CloseFile       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  933

           22.3.3    FinalizeResourceTables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  934

           22.3.4    GetResourceStringCurrentValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 934

           22.3.5    GetResourceStringDefaultValue                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 935

           22.3.6    GetResourceStringHash               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  935

           22.3.7    GetResourceStringName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  936

           22.3.8    Hash     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  937

           22.3.9    LoadResString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  937

           22.3.10   ParamStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  938

           22.3.11   ResetResourceTables            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  938

           22.3.12   ResourceStringCount            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  938

           22.3.13   ResourceStringTableCount                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  939

           22.3.14   SetResourceStrings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  939

           22.3.15   SetResourceStringValue              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  940

           22.3.16   SetUnitResourceStrings              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  941


23   Reference for unit 'oldlinux'                                                                                      942

    23.1   Utility routines        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  942

    23.2   Terminal functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  942

    23.3   System information           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  942

    23.4   Signals     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  943

    23.5   Process handling          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  943

    23.6   Directory handling routines              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  943

    23.7   Pipes, FIFOs and streams                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  944

    23.8   General File handling routines                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  944

    23.9   File Input/Output routines               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  944

    23.10  Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  944

    23.11  Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  944

           23.11.1   Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  944

           23.11.2   Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  984



                                                                 58

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           23.11.3   Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  993

    23.12  Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  993

           23.12.1   Access     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  993

           23.12.2   Alarm      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  994

           23.12.3   AssignPipe         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  995

           23.12.4   AssignStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  996

           23.12.5   Basename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  997

           23.12.6   CFMakeRaw            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  998

           23.12.7   CFSetISpeed          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  998

           23.12.8   CFSetOSpeed          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  999

           23.12.9   Chmod         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  999

           23.12.10  Chown      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1000

           23.12.11  Clone      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1001

           23.12.12  CloseDir      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1003

           23.12.13  CreateShellArgV           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1003

           23.12.14  Dirname       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1004

           23.12.15  Dup      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1005

           23.12.16  Dup2       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1006

           23.12.17  EpochToLocal           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1006

           23.12.18  Execl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1007

           23.12.19  Execle     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1008

           23.12.20  Execlp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1009

           23.12.21  Execv      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1010

           23.12.22  Execve     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1011

           23.12.23  Execvp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1012

           23.12.24  ExitProcess        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1013

           23.12.25  Fcntl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1013

           23.12.26  fdClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1014

           23.12.27  fdFlush       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1014

           23.12.28  fdOpen        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1014

           23.12.29  fdRead     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1015

           23.12.30  fdSeek     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1016

           23.12.31  fdTruncate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1017

           23.12.32  fdWrite       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1017

           23.12.33  FD_Clr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1017

           23.12.34  FD_IsSet        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1018

           23.12.35  FD_Set        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1018

           23.12.36  FD_Zero       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1018

           23.12.37  FExpand         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1018

           23.12.38  Flock      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1019



                                                                 59

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           23.12.39  FNMatch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1019

           23.12.40  Fork     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1020

           23.12.41  FReName         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1020

           23.12.42  FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1021

           23.12.43  FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1022

           23.12.44  FSStat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1022

           23.12.45  FStat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1023

           23.12.46  GetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1024

           23.12.47  GetDateTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1025

           23.12.48  GetDomainName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1025

           23.12.49  GetEGid         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1026

           23.12.50  GetEnv        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1026

           23.12.51  GetEpochTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1027

           23.12.52  GetEUid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1027

           23.12.53  GetFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1028

           23.12.54  GetGid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1029

           23.12.55  GetHostName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1029

           23.12.56  GetLocalTimezone            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1030

           23.12.57  GetPid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1030

           23.12.58  GetPPid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1030

           23.12.59  GetPriority        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1031

           23.12.60  GetTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1031

           23.12.61  GetTimeOfDay           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1032

           23.12.62  GetTimezoneFile           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1032

           23.12.63  GetUid        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1033

           23.12.64  Glob     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1033

           23.12.65  Globfree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1034

           23.12.66  IOCtl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1034

           23.12.67  IOperm        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1035

           23.12.68  IoPL     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1035

           23.12.69  IsATTY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1035

           23.12.70  Kill     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1036

           23.12.71  Link     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1036

           23.12.72  LocalToEpoch           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1037

           23.12.73  Lstat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1038

           23.12.74  mkFifo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1039

           23.12.75  MMap       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1040

           23.12.76  MUnMap          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1041

           23.12.77  NanoSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1041

           23.12.78  Nice     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1042



                                                                 60

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           23.12.79  Octal      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1043

           23.12.80  OpenDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1043

           23.12.81  Pause      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1045

           23.12.82  PClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1045

           23.12.83  POpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1045

           23.12.84  ReadDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1046

           23.12.85  ReadLink        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1046

           23.12.86  ReadTimezoneFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1048

           23.12.87  SeekDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1048

           23.12.88  Select     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1048

           23.12.89  SelectText      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1049

           23.12.90  SetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1050

           23.12.91  SetDateTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1050

           23.12.92  SetPriority        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1050

           23.12.93  SetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1051

           23.12.94  Shell    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1051

           23.12.95  SigAction       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1052

           23.12.96  Signal     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1053

           23.12.97  SigPending         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1054

           23.12.98  SigProcMask          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1054

           23.12.99  SigRaise      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1055

           23.12.100 SigSuspend         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1056

           23.12.101 StringToPPChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1056

           23.12.102 SymLink         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1057

           23.12.103 SysCall       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1058

           23.12.104 Sysinfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1058

           23.12.105 S_ISBLK         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1059

           23.12.106 S_ISCHR         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1060

           23.12.107 S_ISDIR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1060

           23.12.108 S_ISFIFO        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1060

           23.12.109 S_ISLNK         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1060

           23.12.110 S_ISREG         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1061

           23.12.111 S_ISSOCK        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1061

           23.12.112 TCDrain         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1062

           23.12.113 TCFlow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1062

           23.12.114 TCFlush       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1062

           23.12.115 TCGetAttr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1063

           23.12.116 TCGetPGrp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1063

           23.12.117 TCSendBreak          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1064

           23.12.118 TCSetAttr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1064



                                                                 61

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           23.12.119 TCSetPGrp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1065

           23.12.120 TellDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1065

           23.12.121 TTYname         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1065

           23.12.122 Umask      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1066

           23.12.123 Uname      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1066

           23.12.124 UnLink        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1066

           23.12.125 Utime      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1067

           23.12.126 WaitPid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1068

           23.12.127 WaitProcess        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1068

           23.12.128 WEXITSTATUS               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1069

           23.12.129 WIFEXITED            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1069

           23.12.130 WIFSIGNALED               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1069

           23.12.131 WIFSTOPPED             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1070

           23.12.132 WSTOPSIG             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1070

           23.12.133 WTERMSIG             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1070

           23.12.134 W_EXITCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1070

           23.12.135 W_STOPCODE                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1071


24   Reference for unit 'ports'                                                                                       1072

    24.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1072

    24.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1072

           24.2.1    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1072

    24.3   tport    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  1073

           24.3.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1073

           24.3.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1073

           24.3.3    tport.pp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1073

    24.4   tportl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  1073

           24.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1073

           24.4.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1074

           24.4.3    tportl.pp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1074

    24.5   tportw      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  1074

           24.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1074

           24.5.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1074

           24.5.3    tportw.pp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1074


25   Reference for unit 'printer'                                                                                     1075

    25.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1075

    25.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1075

           25.2.1    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1075

    25.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1075

           25.3.1    AssignLst       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1075



                                                                 62

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           25.3.2    InitPrinter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1076

           25.3.3    IsLstAvailable       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1076


26   Reference for unit 'Sockets'                                                                                     1077

    26.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1077

    26.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1077

    26.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1077

           26.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1077

           26.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1096

    26.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1099

           26.4.1    Accept     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1099

           26.4.2    Bind     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1101

           26.4.3    CloseSocket        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1102

           26.4.4    Connect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1102

           26.4.5    fpaccept      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1104

           26.4.6    fpbind     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1105

           26.4.7    fpconnect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1106

           26.4.8    fpgetpeername          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1107

           26.4.9    fpgetsockname          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1108

           26.4.10   fpgetsockopt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1108

           26.4.11   fplisten      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1109

           26.4.12   fprecv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1109

           26.4.13   fprecvfrom         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1110

           26.4.14   fpsend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1110

           26.4.15   fpsendto      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1110

           26.4.16   fpsetsockopt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1111

           26.4.17   fpshutdown         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1111

           26.4.18   fpsocket      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1112

           26.4.19   fpsocketpair       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1112

           26.4.20   GetPeerName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1112

           26.4.21   GetSocketName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1113

           26.4.22   GetSocketOptions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1113

           26.4.23   HostAddrToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1114

           26.4.24   HostAddrToStr6            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1114

           26.4.25   HostToNet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1114

           26.4.26   htonl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1115

           26.4.27   htons      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1115

           26.4.28   Listen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1115

           26.4.29   NetAddrToStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1115

           26.4.30   NetAddrToStr6          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1116
                                                                 63

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           26.4.31   NetToHost          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1116

           26.4.32   NToHl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1116

           26.4.33   NToHs      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1116

           26.4.34   Recv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1117

           26.4.35   RecvFrom        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1117

           26.4.36   Send     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1118

           26.4.37   SendTo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1118

           26.4.38   SetSocketOptions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1118

           26.4.39   ShortHostToNet            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1119

           26.4.40   ShortNetToHost            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1119

           26.4.41   Shutdown        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1119

           26.4.42   Sock2File       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1120

           26.4.43   Sock2Text       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1120

           26.4.44   Socket     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1120

           26.4.45   socketerror        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1121

           26.4.46   SocketPair      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1121

           26.4.47   Str2UnixSockAddr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1121

           26.4.48   StrToHostAddr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1122

           26.4.49   StrToHostAddr6            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1122

           26.4.50   StrToNetAddr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1122

           26.4.51   StrToNetAddr6          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1122


27   Reference for unit 'strings'                                                                                     1123

    27.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1123

    27.2   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1123

           27.2.1    stralloc      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1123

           27.2.2    strcat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1123

           27.2.3    strcomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1124

           27.2.4    strcopy       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1124

           27.2.5    strdispose      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1125

           27.2.6    strecopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1125

           27.2.7    strend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1126

           27.2.8    stricomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1127

           27.2.9    strlcat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1127

           27.2.10   strlcomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1128

           27.2.11   strlcopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1129

           27.2.12   strlen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1129

           27.2.13   strlicomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1130

           27.2.14   strlower      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1130

           27.2.15   strmove       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1131
                                                                 64

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           27.2.16   strnew     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1131

           27.2.17   strpas     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1132

           27.2.18   strpcopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1133

           27.2.19   strpos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1133

           27.2.20   strrscan      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1134

           27.2.21   strscan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1134

           27.2.22   strupper      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1135


28   Reference for unit 'strutils'                                                                                    1136

    28.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1136

    28.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1136

           28.2.1    Resource strings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1136

           28.2.2    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1136

           28.2.3    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1137

    28.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1138

           28.3.1    AddChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1138

           28.3.2    AddCharR           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1138

           28.3.3    AnsiContainsStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1138

           28.3.4    AnsiContainsText            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1139

           28.3.5    AnsiEndsStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1139

           28.3.6    AnsiEndsText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1139

           28.3.7    AnsiIndexStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1139

           28.3.8    AnsiIndexText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1140

           28.3.9    AnsiLeftStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1140

           28.3.10   AnsiMatchStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1140

           28.3.11   AnsiMatchText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1141

           28.3.12   AnsiMidStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1141

           28.3.13   AnsiProperCase            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1141

           28.3.14   AnsiReplaceStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1142

           28.3.15   AnsiReplaceText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1142

           28.3.16   AnsiResemblesText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1142

           28.3.17   AnsiReverseString           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1142

           28.3.18   AnsiRightStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1143

           28.3.19   AnsiStartsStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1143

           28.3.20   AnsiStartsText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1143

           28.3.21   BinToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1144

           28.3.22   Copy2Space         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1144

           28.3.23   Copy2SpaceDel          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1144

           28.3.24   Copy2Symb          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1145

           28.3.25   Copy2SymbDel           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1145
                                                                 65

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           28.3.26   Dec2Numb           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1145

           28.3.27   DecodeSoundexInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1146

           28.3.28   DecodeSoundexWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1146

           28.3.29   DelChars        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1146

           28.3.30   DelSpace        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1146

           28.3.31   DelSpace1       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1147

           28.3.32   DupeString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1147

           28.3.33   ExtractDelimited          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1147

           28.3.34   ExtractSubstr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1148

           28.3.35   ExtractWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1148

           28.3.36   ExtractWordPos            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1148

           28.3.37   FindPart        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1149

           28.3.38   GetCmdLineArg             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1149

           28.3.39   Hex2Dec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1150

           28.3.40   HexToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1150

           28.3.41   IfThen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1150

           28.3.42   IntToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1150

           28.3.43   IntToRoman           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1151

           28.3.44   IsEmptyStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1151

           28.3.45   IsWild     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1151

           28.3.46   IsWordPresent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1152

           28.3.47   LeftBStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1152

           28.3.48   LeftStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1152

           28.3.49   MidBStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1153

           28.3.50   MidStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1153

           28.3.51   NPos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1153

           28.3.52   Numb2Dec           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1154

           28.3.53   Numb2USA           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1154

           28.3.54   PadCenter       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1154

           28.3.55   PadLeft       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1154

           28.3.56   PadRight        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1155

           28.3.57   PosEx      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1155

           28.3.58   PosSet     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1155

           28.3.59   PosSetEx        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1155

           28.3.60   RandomFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1156

           28.3.61   Removeleadingchars             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1156

           28.3.62   RemovePadChars            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1156

           28.3.63   RemoveTrailingChars              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1157

           28.3.64   ReverseString        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1157

           28.3.65   RightBStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1157



                                                                 66

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           28.3.66   RightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1158

           28.3.67   RomanToInt           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1158

           28.3.68   RPos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1158

           28.3.69   RPosex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1158

           28.3.70   SearchBuf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1159

           28.3.71   Soundex       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1159

           28.3.72   SoundexCompare            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1160

           28.3.73   SoundexInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1160

           28.3.74   SoundexProc          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1160

           28.3.75   SoundexSimilar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1161

           28.3.76   SoundexWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1161

           28.3.77   StringsReplace         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1161

           28.3.78   StuffString        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1162

           28.3.79   Tab2Space          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1162

           28.3.80   TrimLeftSet        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1162

           28.3.81   TrimRightSet         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1162

           28.3.82   TrimSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1163

           28.3.83   WordCount          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1163

           28.3.84   WordPosition         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1163

           28.3.85   XorDecode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1164

           28.3.86   XorEncode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1164

           28.3.87   XorString       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1164


29   Reference for unit 'System'                                                                                      1165

    29.1   Miscellaneous functions             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1165

    29.2   Operating System functions               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1165

    29.3   String handling         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1165

    29.4   Mathematical routines            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1165

    29.5   Memory management functions                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1166

    29.6   File handling functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1166

    29.7   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1166

    29.8   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1167

           29.8.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1167

           29.8.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1188

           29.8.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1209

    29.9   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1211

           29.9.1    abs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1211

           29.9.2    AbstractError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1212

           29.9.3    AcquireExceptionObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1212

           29.9.4    AddExitProc          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1212
                                                                 67

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.5    Addr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1213

           29.9.6    Align      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1213

           29.9.7    AllocMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1214

           29.9.8    AnsiToUtf8         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1214

           29.9.9    Append        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1214

           29.9.10   arctan     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1215

           29.9.11   ArrayStringToPPchar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1215

           29.9.12   Assert     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1216

           29.9.13   Assign     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1216

           29.9.14   Assigned      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1217

           29.9.15   BasicEventCreate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1217

           29.9.16   basiceventdestroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1218

           29.9.17   basiceventResetEvent             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1218

           29.9.18   basiceventSetEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1218

           29.9.19   basiceventWaitFor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1218

           29.9.20   BeginThread          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1218

           29.9.21   BEtoN      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1219

           29.9.22   binStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1219

           29.9.23   BlockRead          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

           29.9.24   BlockWrite         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1221

           29.9.25   Break      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1221

           29.9.26   chdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1222

           29.9.27   chr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1223

           29.9.28   Close      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1223

           29.9.29   CompareByte          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1224

           29.9.30   CompareChar          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1225

           29.9.31   CompareChar0           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1226

           29.9.32   CompareDWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1227

           29.9.33   CompareWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1228

           29.9.34   Concat        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1229

           29.9.35   Continue        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1229

           29.9.36   Copy     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1230

           29.9.37   cos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1231

           29.9.38   Cseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1231

           29.9.39   Dec      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1232

           29.9.40   DefaultAnsi2WideMove                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1233

           29.9.41   DefaultWide2AnsiMove                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1233

           29.9.42   Delete     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1233

           29.9.43   Dispose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1234

           29.9.44   DoneCriticalsection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1235



                                                                 68

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.45   Dseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1235

           29.9.46   DumpExceptionBackTrace                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1236

           29.9.47   Dump_Stack           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1236

           29.9.48   DynArraySetLength              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1236

           29.9.49   EndThread          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1236

           29.9.50   EnterCriticalsection           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1237

           29.9.51   EOF      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1237

           29.9.52   EOLn       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1238

           29.9.53   Erase      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1239

           29.9.54   Error      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1239

           29.9.55   Exclude       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1239

           29.9.56   Exit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1241

           29.9.57   exp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1242

           29.9.58   FilePos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1242

           29.9.59   FileSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1243

           29.9.60   FillByte      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1244

           29.9.61   FillChar      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1245

           29.9.62   FillDWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1245

           29.9.63   FillWord      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1246

           29.9.64   FindResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1246

           29.9.65   float_raise     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1247

           29.9.66   Flush      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1247

           29.9.67   FlushThread          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1248

           29.9.68   frac     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1248

           29.9.69   Freemem         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1248

           29.9.70   Freememory         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1249

           29.9.71   FreeResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1249

           29.9.72   GetCurrentThreadId             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1249

           29.9.73   getdir     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1250

           29.9.74   GetFPCHeapStatus               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1250

           29.9.75   GetHeapStatus          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1250

           29.9.76   GetMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1251

           29.9.77   GetMemory          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1251

           29.9.78   GetMemoryManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1251

           29.9.79   GetProcessID         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1251

           29.9.80   GetThreadID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1252

           29.9.81   GetThreadManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1252

           29.9.82   GetVariantManager              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1252

           29.9.83   GetWideStringManager                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1252

           29.9.84   get_caller_addr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1253



                                                                 69

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.85   get_caller_frame       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1253

           29.9.86   get_frame       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1253

           29.9.87   halt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1253

           29.9.88   hexStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1254

           29.9.89   hi    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1254

           29.9.90   High     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1255

           29.9.91   HINSTANCE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1256

           29.9.92   Inc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1256

           29.9.93   Include       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1257

           29.9.94   IndexByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1258

           29.9.95   IndexChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1258

           29.9.96   IndexChar0         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1259

           29.9.97   IndexDWord           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1259

           29.9.98   Indexword       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1260

           29.9.99   InitCriticalSection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1261

           29.9.100  InitThread         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1261

           29.9.101  InitThreadVars         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1261

           29.9.102  Insert     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1262

           29.9.103  int   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1262

           29.9.104  InterlockedCompareExchange                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1263

           29.9.105  InterLockedDecrement             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1263

           29.9.106  InterLockedExchange              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1264

           29.9.107  InterLockedExchangeAdd                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1264

           29.9.108  InterLockedIncrement             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1264

           29.9.109  IOResult        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1265

           29.9.110  IsMemoryManagerSet               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1266

           29.9.111  KillThread         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1266

           29.9.112  LeaveCriticalsection           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1267

           29.9.113  Length     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1267

           29.9.114  LEtoN      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1268

           29.9.115  ln    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1268

           29.9.116  lo    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1268

           29.9.117  LoadResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1269

           29.9.118  LockResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1269

           29.9.119  longjmp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1270

           29.9.120  Low      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1270

           29.9.121  lowerCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1270

           29.9.122  MemSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1271

           29.9.123  mkdir      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1271

           29.9.124  Move       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1272



                                                                 70

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.125  MoveChar0          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1272

           29.9.126  New      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1273

           29.9.127  NtoBE      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1273

           29.9.128  NtoLE      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1273

           29.9.129  Null     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1274

           29.9.130  OctStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1274

           29.9.131  odd      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1274

           29.9.132  Ofs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1275

           29.9.133  operator *(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1275

           29.9.134  operator **(variant, variant):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1276

           29.9.135  operator +(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1276

           29.9.136  operator -(variant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1276

           29.9.137  operator -(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1276

           29.9.138  operator /(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1277

           29.9.139  operator :=(ansistring):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1277

           29.9.140  operator :=(ansistring):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1277

           29.9.141  operator :=(Boolean):  olevariant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1277

           29.9.142  operator :=(Boolean):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1278

           29.9.143  operator :=(Byte):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1278

           29.9.144  operator :=(Byte):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1278

           29.9.145  operator :=(Char):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1278

           29.9.146  operator :=(Char):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1278

           29.9.147  operator :=(currency):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1279

           29.9.148  operator :=(currency):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1279

           29.9.149  operator :=(double):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1279

           29.9.150  operator :=(double):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1279

           29.9.151  operator :=(DWord):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1280

           29.9.152  operator :=(DWord):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1280

           29.9.153  operator :=(Int64):  olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1280

           29.9.154  operator :=(Int64):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1280

           29.9.155  operator :=(longbool):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1280

           29.9.156  operator :=(longbool):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1281

           29.9.157  operator :=(LongInt):  olevariant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1281

           29.9.158  operator :=(LongInt):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1281

           29.9.159  operator :=(olevariant):  ansistring              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1281

           29.9.160  operator :=(olevariant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1282

           29.9.161  operator :=(olevariant):  Byte             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1282

           29.9.162  operator :=(olevariant):  Char             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1282

           29.9.163  operator :=(olevariant):  currency              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1282

           29.9.164  operator :=(olevariant):  double             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1282



                                                                 71

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.165  operator :=(olevariant):  DWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1283

           29.9.166  operator :=(olevariant):  Int64            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1283

           29.9.167  operator :=(olevariant):  longbool              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1283

           29.9.168  operator :=(olevariant):  LongInt               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1283

           29.9.169  operator :=(olevariant):  qword              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1284

           29.9.170  operator :=(olevariant):  Real             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1284

           29.9.171  operator :=(olevariant):  ShortInt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1284

           29.9.172  operator :=(olevariant):  shortstring                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1284

           29.9.173  operator :=(olevariant):  SmallInt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1284

           29.9.174  operator :=(olevariant):  TDateTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1285

           29.9.175  operator :=(olevariant):  TError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1285

           29.9.176  operator :=(olevariant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1285

           29.9.177  operator :=(olevariant):  widechar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1285

           29.9.178  operator :=(olevariant):  widestring              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1286

           29.9.179  operator :=(olevariant):  Word               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1286

           29.9.180  operator :=(olevariant):  wordbool                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1286

           29.9.181  operator :=(qword):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1286

           29.9.182  operator :=(qword):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1286

           29.9.183  operator :=(Real):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1287

           29.9.184  operator :=(Real):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1287

           29.9.185  operator :=(real48):  double             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1287

           29.9.186  operator :=(ShortInt):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1287

           29.9.187  operator :=(ShortInt):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1287

           29.9.188  operator :=(shortstring):  olevariant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1287

           29.9.189  operator :=(shortstring):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1288

           29.9.190  operator :=(SmallInt):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1288

           29.9.191  operator :=(SmallInt):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1288

           29.9.192  operator :=(TDateTime):  olevariant                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1288

           29.9.193  operator :=(TDateTime):  variant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1289

           29.9.194  operator :=(TError):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1289

           29.9.195  operator :=(TError):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1289

           29.9.196  operator :=(variant):  ansistring            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1289

           29.9.197  operator :=(variant):  Boolean             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1289

           29.9.198  operator :=(variant):  Byte              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1290

           29.9.199  operator :=(variant):  Char              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1290

           29.9.200  operator :=(variant):  currency              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1290

           29.9.201  operator :=(variant):  double              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1290

           29.9.202  operator :=(variant):  DWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1290

           29.9.203  operator :=(variant):  Int64             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1291

           29.9.204  operator :=(variant):  longbool              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1291



                                                                 72

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.205  operator :=(variant):  LongInt             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1291

           29.9.206  operator :=(variant):  olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1291

           29.9.207  operator :=(variant):  qword             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1291

           29.9.208  operator :=(variant):  Real           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1292

           29.9.209  operator :=(variant):  ShortInt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1292

           29.9.210  operator :=(variant):  shortstring              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1292

           29.9.211  operator :=(variant):  SmallInt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1292

           29.9.212  operator :=(variant):  TDateTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1292

           29.9.213  operator :=(variant):  TError              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1293

           29.9.214  operator :=(variant):  widechar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1293

           29.9.215  operator :=(variant):  widestring               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1293

           29.9.216  operator :=(variant):  Word              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1293

           29.9.217  operator :=(variant):  wordbool              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1293

           29.9.218  operator :=(widechar):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1294

           29.9.219  operator :=(widechar):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1294

           29.9.220  operator :=(widestring):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1294

           29.9.221  operator :=(widestring):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1294

           29.9.222  operator :=(Word):  olevariant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1295

           29.9.223  operator :=(Word):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1295

           29.9.224  operator :=(wordbool):  olevariant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1295

           29.9.225  operator :=(wordbool):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1295

           29.9.226  operator <(variant, variant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1295

           29.9.227  operator <=(variant, variant):  Boolean                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *296

           29.9.228  operator =(variant, variant):  Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *296

           29.9.229  operator >(variant, variant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1296

           29.9.230  operator >=(variant, variant):  Boolean                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *296

           29.9.231  operator and(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *297

           29.9.232  operator div(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *297

           29.9.233  operator mod(variant, variant):  variant                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *297

           29.9.234  operator not(variant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1297

           29.9.235  operator or(variant, variant):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1298

           29.9.236  operator shl(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *298

           29.9.237  operator shr(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *298

           29.9.238  operator xor(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *298

           29.9.239  Ord      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1299

           29.9.240  Paramcount         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1299

           29.9.241  ParamStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1300

           29.9.242  pi    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1300

           29.9.243  Pos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1301

           29.9.244  Pred     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1302



                                                                 73

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.245  prefetch      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1302

           29.9.246  ptr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1302

           29.9.247  RaiseList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1303

           29.9.248  Random        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1303

           29.9.249  Randomize          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1304

           29.9.250  Read     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1304

           29.9.251  ReadBarrier        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1305

           29.9.252  ReadDependencyBarrier               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1305

           29.9.253  ReadLn        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1306

           29.9.254  ReadWriteBarrier            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1306

           29.9.255  Real2Double          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1306

           29.9.256  ReAllocMem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1307

           29.9.257  ReAllocMemory             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1307

           29.9.258  ReleaseExceptionObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1308

           29.9.259  Rename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1308

           29.9.260  Reset      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1308

           29.9.261  ResumeThread           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1309

           29.9.262  Rewrite       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1310

           29.9.263  rmdir      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1310

           29.9.264  round      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1311

           29.9.265  RTLEventCreate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1312

           29.9.266  RTLeventdestroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1312

           29.9.267  RTLeventResetEvent             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1312

           29.9.268  RTLeventSetEvent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1312

           29.9.269  RTLeventsync           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1313

           29.9.270  RTLeventWaitFor             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1313

           29.9.271  RunError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1313

           29.9.272  Seek     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1314

           29.9.273  SeekEOF         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1314

           29.9.274  SeekEOLn        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1315

           29.9.275  Seg   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1316

           29.9.276  Setjmp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1316

           29.9.277  SetLength       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1317

           29.9.278  SetMemoryManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1318

           29.9.279  SetMemoryMutexManager                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1318

           29.9.280  SetString       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1318

           29.9.281  SetTextBuf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1318

           29.9.282  SetTextLineEnding           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1319

           29.9.283  SetThreadManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1320

           29.9.284  SetVariantManager           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1320



                                                                 74

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.285  SetWideStringManager                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1320

           29.9.286  ShortCompareText            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1321

           29.9.287  sin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1321

           29.9.288  SizeOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1322

           29.9.289  SizeofResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1322

           29.9.290  Space      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1323

           29.9.291  Sptr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1323

           29.9.292  sqr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1323

           29.9.293  sqrt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1324

           29.9.294  Sseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1324

           29.9.295  Str   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1325

           29.9.296  StringOfChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1325

           29.9.297  StringToPPChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1326

           29.9.298  StringToWideChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1326

           29.9.299  strlen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1327

           29.9.300  strpas     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1327

           29.9.301  Succ     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1327

           29.9.302  SuspendThread          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1328

           29.9.303  Swap     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1328

           29.9.304  SwapEndian         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1329

           29.9.305  SysAllocMem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1329

           29.9.306  SysAssert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1329

           29.9.307  SysBackTraceStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1329

           29.9.308  SysFreemem         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1330

           29.9.309  SysFreememSize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1330

           29.9.310  SysGetFPCHeapStatus                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1330

           29.9.311  SysGetHeapStatus            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1330

           29.9.312  SysGetmem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1330

           29.9.313  SysInitExceptions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1331

           29.9.314  SysInitFPU         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1331

           29.9.315  SysInitStdIO         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1331

           29.9.316  SysMemSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1331

           29.9.317  SysReAllocMem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1331

           29.9.318  SysResetFPU          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1332

           29.9.319  SysSetCtrlBreakHandler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1332

           29.9.320  SysTryResizeMem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1332

           29.9.321  ThreadGetPriority           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1332

           29.9.322  ThreadSetPriority           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1333

           29.9.323  ThreadSwitch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1333

           29.9.324  trunc      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1333



                                                                 75

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.9.325  Truncate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1334

           29.9.326  UCS4StringToWideString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1334

           29.9.327  Unassigned         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1334

           29.9.328  UnicodeToUtf8          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1335

           29.9.329  UniqueString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1335

           29.9.330  UnlockResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1335

           29.9.331  upCase        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1335

           29.9.332  UTF8Decode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1336

           29.9.333  UTF8Encode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1336

           29.9.334  Utf8ToAnsi         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1336

           29.9.335  Utf8ToUnicode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1337

           29.9.336  Val   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1337

           29.9.337  VarArrayGet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1337

           29.9.338  VarArrayPut          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1338

           29.9.339  VarArrayRedim          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1338

           29.9.340  VarCast       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1338

           29.9.341  WaitForThreadTerminate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1339

           29.9.342  WideCharLenToString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1339

           29.9.343  WideCharLenToStrVar                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1339

           29.9.344  WideCharToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1339

           29.9.345  WideCharToStrVar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1340

           29.9.346  WideStringToUCS4String                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1340

           29.9.347  Write      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1340

           29.9.348  WriteBarrier         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1341

           29.9.349  WriteLn       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1341

    29.10  IDispatch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1342

           29.10.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1342

           29.10.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1342

           29.10.3   IDispatch.GetTypeInfoCount                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1342

           29.10.4   IDispatch.GetTypeInfo            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1342

           29.10.5   IDispatch.GetIDsOfNames               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1342

           29.10.6   IDispatch.Invoke          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1343

    29.11  IInvokable      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1343

           29.11.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1343

    29.12  IUnknown        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1343

           29.12.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1343

           29.12.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1343

           29.12.3   IUnknown.QueryInterface               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1343

           29.12.4   IUnknown._AddRef            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1343

           29.12.5   IUnknown._Release           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1344



                                                                 76

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    29.13  TAggregatedObject            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1344

           29.13.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1344

           29.13.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1344

           29.13.3   Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1344

           29.13.4   TAggregatedObject.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1344

           29.13.5   TAggregatedObject.Controller                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1345

    29.14  TContainedObject             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1345

           29.14.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1345

    29.15  TInterfacedObject            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1345

           29.15.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1345

           29.15.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1345

           29.15.3   Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1345

           29.15.4   TInterfacedObject.AfterConstruction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1345

           29.15.5   TInterfacedObject.BeforeDestruction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1346

           29.15.6   TInterfacedObject.NewInstance                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1346

           29.15.7   TInterfacedObject.RefCount                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1346

    29.16  TObject       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  1346

           29.16.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1346

           29.16.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1347

           29.16.3   TObject.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1347

           29.16.4   TObject.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1347

           29.16.5   TObject.newinstance            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1348

           29.16.6   TObject.FreeInstance             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1348

           29.16.7   TObject.SafeCallException                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1348

           29.16.8   TObject.DefaultHandler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1349

           29.16.9   TObject.Free         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1349

           29.16.10  TObject.InitInstance           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1349

           29.16.11  TObject.CleanupInstance               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1349

           29.16.12  TObject.ClassType           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1350

           29.16.13  TObject.ClassInfo           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1350

           29.16.14  TObject.ClassName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1350

           29.16.15  TObject.ClassNameIs              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1350

           29.16.16  TObject.ClassParent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1351

           29.16.17  TObject.InstanceSize             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1351

           29.16.18  TObject.InheritsFrom             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1351

           29.16.19  TObject.StringMessageTable                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1351

           29.16.20  TObject.Dispatch            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1352

           29.16.21  TObject.DispatchStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1352

           29.16.22  TObject.MethodAddress               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1352

           29.16.23  TObject.MethodName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1352



                                                                 77

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           29.16.24  TObject.FieldAddress             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1353

           29.16.25  TObject.AfterConstruction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1353

           29.16.26  TObject.BeforeDestruction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1353

           29.16.27  TObject.DefaultHandlerStr                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1353

           29.16.28  TObject.GetInterface             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1354

           29.16.29  TObject.GetInterfaceByStr                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1354

           29.16.30  TObject.GetInterfaceEntry                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1354

           29.16.31  TObject.GetInterfaceEntryByStr                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1354

           29.16.32  TObject.GetInterfaceTable                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1355


30   Reference for unit 'sysutils'                                                                                    1356

    30.1   Miscellaneous conversion routines               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1356

    30.2   Date/time routines           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1356

    30.3   FileName handling routines               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1356

    30.4   File input/output routines            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1356

    30.5   PChar related functions             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1357

    30.6   Localization support           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1359

    30.7   Formatting strings           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1359

    30.8   String functions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1360

    30.9   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1360

    30.10  Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1360

    30.11  Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1361

           30.11.1   Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1361

           30.11.2   Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1368

           30.11.3   Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1374

    30.12  Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1377

           30.12.1   AbandonSignalHandler                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1377

           30.12.2   Abort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1377

           30.12.3   AddDisk       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1378

           30.12.4   AddTerminateProc            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1378

           30.12.5   AdjustLineBreaks            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1378

           30.12.6   AnsiCompareFileName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1379

           30.12.7   AnsiCompareStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1379

           30.12.8   AnsiCompareText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1380

           30.12.9   AnsiDequotedStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1381

           30.12.10  AnsiExtractQuotedStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1381

           30.12.11  AnsiLastChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1382

           30.12.12  AnsiLowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1383

           30.12.13  AnsiLowerCaseFileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1383

           30.12.14  AnsiPos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1384
                                                                 78

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.15  AnsiQuotedStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1384

           30.12.16  AnsiSameStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1384

           30.12.17  AnsiSameText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1384

           30.12.18  AnsiStrComp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1385

           30.12.19  AnsiStrIComp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1385

           30.12.20  AnsiStrLastChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1386

           30.12.21  AnsiStrLComp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1387

           30.12.22  AnsiStrLIComp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1388

           30.12.23  AnsiStrLower         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1389

           30.12.24  AnsiStrPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1389

           30.12.25  AnsiStrRScan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1390

           30.12.26  AnsiStrScan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1390

           30.12.27  AnsiStrUpper         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1390

           30.12.28  AnsiUpperCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1391

           30.12.29  AnsiUpperCaseFileName                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1391

           30.12.30  AppendStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1392

           30.12.31  ApplicationName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1392

           30.12.32  AssignStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1393

           30.12.33  BCDToInt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1393

           30.12.34  Beep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1394

           30.12.35  BoolToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1394

           30.12.36  ByteToCharIndex             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1394

           30.12.37  ByteToCharLen             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1394

           30.12.38  ByteType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1395

           30.12.39  CallTerminateProcs             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1395

           30.12.40  ChangeFileExt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1395

           30.12.41  CharToByteLen             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1396

           30.12.42  CompareMem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1396

           30.12.43  CompareMemRange                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1396

           30.12.44  CompareStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1397

           30.12.45  CompareText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1398

           30.12.46  ComposeDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1398

           30.12.47  CreateDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1399

           30.12.48  CreateGUID           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1399

           30.12.49  CurrentYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1400

           30.12.50  CurrToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1400

           30.12.51  CurrToStrF         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1400

           30.12.52  Date     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1401

           30.12.53  DateTimeToFileDate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1401

           30.12.54  DateTimeToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1402



                                                                 79

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.55  DateTimeToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1402

           30.12.56  DateTimeToSystemTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1403

           30.12.57  DateTimeToTimeStamp                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1404

           30.12.58  DateToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1404

           30.12.59  DayOfWeek          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1405

           30.12.60  DecodeDate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1405

           30.12.61  DecodeDateFully           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1406

           30.12.62  DecodeTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1406

           30.12.63  DeleteFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1407

           30.12.64  DirectoryExists        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1407

           30.12.65  DiskFree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1408

           30.12.66  DiskSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1408

           30.12.67  DisposeStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1409

           30.12.68  DoDirSeparators           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1409

           30.12.69  EncodeDate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1410

           30.12.70  EncodeTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1410

           30.12.71  ExceptAddr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1411

           30.12.72  ExceptFrameCount            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1411

           30.12.73  ExceptFrames         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1412

           30.12.74  ExceptionErrorMessage               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1412

           30.12.75  ExceptObject         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1412

           30.12.76  ExcludeTrailingBackslash              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1412

           30.12.77  ExcludeTrailingPathDelimiter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1413

           30.12.78  ExecuteProcess         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1413

           30.12.79  ExpandFileName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1413

           30.12.80  ExpandUNCFileName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1414

           30.12.81  ExtractFileDir         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1414

           30.12.82  ExtractFileDrive          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1415

           30.12.83  ExtractFileExt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1415

           30.12.84  ExtractFileName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1415

           30.12.85  ExtractFilePath           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1416

           30.12.86  ExtractRelativepath            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1416

           30.12.87  ExtractShortPathName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1417

           30.12.88  FileAge       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1417

           30.12.89  FileClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1418

           30.12.90  FileCreate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1418

           30.12.91  FileDateToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1419

           30.12.92  FileExists      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1420

           30.12.93  FileGetAttr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1420

           30.12.94  FileGetDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1421



                                                                 80

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.95  FileIsReadOnly         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1422

           30.12.96  FileOpen        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1422

           30.12.97  FileRead        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1423

           30.12.98  FileSearch      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1423

           30.12.99  FileSeek      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1424

           30.12.100 FileSetAttr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1424

           30.12.101 FileSetDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1425

           30.12.102 FileTruncate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1425

           30.12.103 FileWrite       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1425

           30.12.104 FindClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1426

           30.12.105 FindCmdLineSwitch              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1426

           30.12.106 FindFirst       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1426

           30.12.107 FindNext        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1427

           30.12.108 FloattoCurr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1428

           30.12.109 FloatToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1428

           30.12.110 FloatToDecimal            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1428

           30.12.111 FloatToStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1429

           30.12.112 FloatToStrF          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1430

           30.12.113 FloatToText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1432

           30.12.114 FloatToTextFmt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1433

           30.12.115 FmtStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1433

           30.12.116 ForceDirectories          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1434

           30.12.117 Format        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1434

           30.12.118 FormatBuf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1440

           30.12.119 FormatCurr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1440

           30.12.120 FormatDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1441

           30.12.121 FormatFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1441

           30.12.122 FreeAndNil         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1443

           30.12.123 GetAppConfigDir           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1443

           30.12.124 GetAppConfigFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1443

           30.12.125 GetCurrentDir          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1444

           30.12.126 GetDirs       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1444

           30.12.127 GetEnvironmentString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1445

           30.12.128 GetEnvironmentVariable              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1446

           30.12.129 GetEnvironmentVariableCount                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1446

           30.12.130 GetFileHandle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1446

           30.12.131 GetLastOSError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1447

           30.12.132 GetLocalTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1447

           30.12.133 GetModuleName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1447

           30.12.134 GetTempDir           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1447



                                                                 81

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.135 GetTempFileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1448

           30.12.136 GetUserDir         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1448

           30.12.137 GUIDToString           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1448

           30.12.138 HookSignal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1449

           30.12.139 IncAMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1449

           30.12.140 IncludeTrailingBackslash              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1449

           30.12.141 IncludeTrailingPathDelimiter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1450

           30.12.142 IncMonth        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1450

           30.12.143 InquireSignal        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1451

           30.12.144 IntToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1451

           30.12.145 IntToStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1451

           30.12.146 IsDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1452

           30.12.147 IsEqualGUID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1452

           30.12.148 IsLeapYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1453

           30.12.149 IsPathDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1453

           30.12.150 IsValidIdent       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1453

           30.12.151 LastDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1454

           30.12.152 LeftStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1455

           30.12.153 LoadStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1455

           30.12.154 LowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1455

           30.12.155 MSecsToTimeStamp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1456

           30.12.156 NewStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1456

           30.12.157 Now      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1457

           30.12.158 OutOfMemoryError               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1457

           30.12.159 QuotedStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1458

           30.12.160 RaiseLastOSError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1458

           30.12.161 RemoveDir          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1458

           30.12.162 RenameFile         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1459

           30.12.163 ReplaceDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1459

           30.12.164 ReplaceTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1460

           30.12.165 RightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1460

           30.12.166 SafeLoadLibrary           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1460

           30.12.167 SameFileName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1461

           30.12.168 SameText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1461

           30.12.169 SetCurrentDir          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1461

           30.12.170 SetDirSeparators          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1461

           30.12.171 ShowException          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1462

           30.12.172 Sleep    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1462

           30.12.173 SScanf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1462

           30.12.174 StrAlloc      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1463



                                                                 82

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.175 StrBufSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1463

           30.12.176 StrByteType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1464

           30.12.177 strcat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1464

           30.12.178 StrCharLength          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1465

           30.12.179 strcomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1465

           30.12.180 strcopy       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1465

           30.12.181 StrDispose         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1466

           30.12.182 strecopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1466

           30.12.183 strend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1467

           30.12.184 StrFmt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1467

           30.12.185 stricomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1468

           30.12.186 StringReplace        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1469

           30.12.187 StringToGUID           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1469

           30.12.188 strlcat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1470

           30.12.189 strlcomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1470

           30.12.190 strlcopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1471

           30.12.191 strlen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1471

           30.12.192 StrLFmt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1472

           30.12.193 strlicomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1473

           30.12.194 strlower      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1473

           30.12.195 strmove       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1474

           30.12.196 strnew     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1474

           30.12.197 StrNextChar          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1475

           30.12.198 StrPas     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1475

           30.12.199 StrPCopy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1475

           30.12.200 StrPLCopy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1476

           30.12.201 strpos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1476

           30.12.202 strrscan      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1476

           30.12.203 strscan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1477

           30.12.204 StrToBool       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1477

           30.12.205 StrToBoolDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1477

           30.12.206 StrToCurr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1478

           30.12.207 StrToCurrDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1478

           30.12.208 StrToDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1478

           30.12.209 StrToDateDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1479

           30.12.210 StrToDateTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1479

           30.12.211 StrToDateTimeDef            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1480

           30.12.212 StrToFloat         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1480

           30.12.213 StrToFloatDef          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1481

           30.12.214 StrToInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1482



                                                                 83

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.215 StrToInt64         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1482

           30.12.216 StrToInt64Def          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1483

           30.12.217 StrToIntDef        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1483

           30.12.218 StrToQWord           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1484

           30.12.219 StrToQWordDef             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1484

           30.12.220 StrToTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1484

           30.12.221 StrToTimeDef           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1485

           30.12.222 strupper      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1485

           30.12.223 Supports        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1485

           30.12.224 SysErrorMessage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1486

           30.12.225 SystemTimeToDateTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1486

           30.12.226 TextToFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1487

           30.12.227 Time     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1488

           30.12.228 TimeStampToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1488

           30.12.229 TimeStampToMSecs               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1489

           30.12.230 TimeToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1489

           30.12.231 Trim     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1490

           30.12.232 TrimLeft        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1490

           30.12.233 TrimRight       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1491

           30.12.234 TryEncodeDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1492

           30.12.235 TryEncodeTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1492

           30.12.236 TryFloatToCurr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1492

           30.12.237 TryStrToBool         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1493

           30.12.238 TryStrToCurr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1493

           30.12.239 TryStrToDate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1493

           30.12.240 TryStrToDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1494

           30.12.241 TryStrToFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1494

           30.12.242 TryStrToInt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1494

           30.12.243 TryStrToInt64          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1495

           30.12.244 TryStrToQWord             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1495

           30.12.245 TryStrToTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1495

           30.12.246 UnhookSignal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1495

           30.12.247 UpperCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1496

           30.12.248 VendorName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1496

           30.12.249 WideCompareStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1496

           30.12.250 WideCompareText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1497

           30.12.251 WideFmtStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1497

           30.12.252 WideFormat           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1497

           30.12.253 WideFormatBuf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1498

           30.12.254 WideLowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1498



                                                                 84

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.12.255 WideSameStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1498

           30.12.256 WideSameText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1499

           30.12.257 WideUpperCase             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1499

           30.12.258 WrapText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1499

    30.13  EAbort        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  1499

           30.13.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1499

    30.14  EAbstractError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1500

           30.14.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.15  EAccessViolation          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

           30.15.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.16  EAssertionFailed          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

           30.16.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.17  EBusError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1500

           30.17.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.18  EControlC       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1500

           30.18.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.19  EConvertError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1500

           30.19.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.20  EDivByZero         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1500

           30.20.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1500

    30.21  EExternal       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1501

           30.21.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.22  EExternalException             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1501

           30.22.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.23  EFormatError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1501

           30.23.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.24  EHeapMemoryError               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1501

           30.24.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.25  EInOutError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1501

           30.25.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.26  EInterror       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1501

           30.26.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.27  EIntfCastError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1501

           30.27.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1501

    30.28  EIntOverflow         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1502

           30.28.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

    30.29  EInvalidCast         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1502

           30.29.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

    30.30  EInvalidContainer            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

           30.30.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502



                                                                 85

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    30.31  EInvalidInsert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1502

           30.31.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

    30.32  EInvalidOp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1502

           30.32.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

    30.33  EInvalidPointer         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1502

           30.33.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

    30.34  EMathError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1502

           30.34.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1502

    30.35  ENoThreadSupport             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

           30.35.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.36  ENoWideStringSupport                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1503

           30.36.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.37  EOSError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1503

           30.37.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.38  EOutOfMemory              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

           30.38.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.39  EOverflow       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1503

           30.39.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.40  EPackageError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1503

           30.40.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.41  EPrivilege      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1503

           30.41.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1503

    30.42  EPropReadOnly             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

           30.42.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

    30.43  EPropWriteOnly            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

           30.43.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

    30.44  ERangeError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1504

           30.44.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

    30.45  ESafecallException           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

           30.45.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

    30.46  EStackOverflow          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1504

           30.46.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

    30.47  EUnderflow         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1504

           30.47.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

    30.48  EVariantError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1504

           30.48.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1504

           30.48.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1504

           30.48.3   EVariantError.CreateCode                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1505

    30.49  Exception       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1505

           30.49.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1505



                                                                 86

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           30.49.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1505

           30.49.3   Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1505

           30.49.4   Exception.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1505

           30.49.5   Exception.CreateFmt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1506

           30.49.6   Exception.CreateRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1506

           30.49.7   Exception.CreateResFmt                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1506

           30.49.8   Exception.CreateHelp             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1506

           30.49.9   Exception.CreateFmtHelp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1507

           30.49.10  Exception.CreateResHelp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1507

           30.49.11  Exception.CreateResFmtHelp                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1507

           30.49.12  Exception.HelpContext               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1507

           30.49.13  Exception.Message           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1508

    30.50  EZeroDivide        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1508

           30.50.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1508

    30.51  IReadWriteSync            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1508

           30.51.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1508

           30.51.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1508

           30.51.3   IReadWriteSync.BeginRead                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1508

           30.51.4   IReadWriteSync.EndRead                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1509

           30.51.5   IReadWriteSync.BeginWrite                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1509

           30.51.6   IReadWriteSync.EndWrite               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1509

    30.52  TMultiReadExclusiveWriteSynchronizer                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1509

           30.52.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1509

           30.52.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1510

           30.52.3   TMultiReadExclusiveWriteSynchronizer.Create                        .  .  .  .  .  .  .  .  .  .  .  .  .  1510

           30.52.4   TMultiReadExclusiveWriteSynchronizer.Destroy                          .  .  .  .  .  .  .  .  .  .  .  .  1510

           30.52.5   TMultiReadExclusiveWriteSynchronizer.Beginwrite                         .  .  .  .  .  .  .  .  .  .  .  1510

           30.52.6   TMultiReadExclusiveWriteSynchronizer.Endwrite                           .  .  .  .  .  .  .  .  .  .  .  1511

           30.52.7   TMultiReadExclusiveWriteSynchronizer.Beginread                          .  .  .  .  .  .  .  .  .  .  .  1511

           30.52.8   TMultiReadExclusiveWriteSynchronizer.Endread                          .  .  .  .  .  .  .  .  .  .  .  .  1511


31   Reference for unit 'typinfo'                                                                                     1512

    31.1   Auxiliary functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1512

    31.2   Getting or setting property values                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1512

    31.3   Examining published property information                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1512

    31.4   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1512

    31.5   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1512

    31.6   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1513

           31.6.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1513

           31.6.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1515
                                                                 87

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    31.7   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1519

           31.7.1    FindPropInfo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1519

           31.7.2    GetEnumName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1520

           31.7.3    GetEnumNameCount                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1521

           31.7.4    GetEnumProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1522

           31.7.5    GetEnumValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1522

           31.7.6    GetFloatProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1523

           31.7.7    GetInt64Prop         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1524

           31.7.8    GetInterfaceProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1525

           31.7.9    GetMethodProp             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1525

           31.7.10   GetObjectProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1527

           31.7.11   GetObjectPropClass             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1528

           31.7.12   GetOrdProp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1529

           31.7.13   GetPropInfo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1530

           31.7.14   GetPropInfos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1530

           31.7.15   GetPropList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1531

           31.7.16   GetPropValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1532

           31.7.17   GetSetProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1532

           31.7.18   GetStrProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1534

           31.7.19   GetTypeData          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1535

           31.7.20   GetVariantProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1535

           31.7.21   GetWideStrProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1535

           31.7.22   IsPublishedProp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1536

           31.7.23   IsStoredProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1536

           31.7.24   PropIsType         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1537

           31.7.25   PropType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1538

           31.7.26   SetEnumProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1539

           31.7.27   SetFloatProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1539

           31.7.28   SetInt64Prop         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1540

           31.7.29   SetInterfaceProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1540

           31.7.30   SetMethodProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1541

           31.7.31   SetObjectProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1541

           31.7.32   SetOrdProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1542

           31.7.33   SetPropValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1542

           31.7.34   SetSetProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1542

           31.7.35   SetStrProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1543

           31.7.36   SetToString        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1543

           31.7.37   SetVariantProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1544

           31.7.38   SetWideStrProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1545

           31.7.39   StringToSet        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1545



                                                                 88

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    31.8   EPropertyConvertError               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1545

           31.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1545

    31.9   EPropertyError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1546

           31.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1546


32   Reference for unit 'Unix'                                                                                        1547

    32.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1547

    32.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1547

           32.2.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1547

           32.2.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1554

           32.2.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1562

    32.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1563

           32.3.1    AssignPipe         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1563

           32.3.2    AssignStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1564

           32.3.3    FpExecL         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1565

           32.3.4    FpExecLE        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1566

           32.3.5    FpExecLP        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1567

           32.3.6    FpExecLPE          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1568

           32.3.7    FpExecV         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1568

           32.3.8    FpExecVP           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1569

           32.3.9    FpExecVPE          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1570

           32.3.10   fpFlock       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1571

           32.3.11   fpfStatFS       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1571

           32.3.12   fpfsync    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1572

           32.3.13   fpgettimeofday         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1572

           32.3.14   fpStatFS        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1572

           32.3.15   fpSystem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1573

           32.3.16   FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1573

           32.3.17   fStatFS       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1574

           32.3.18   fsync    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1575

           32.3.19   GetDomainName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1576

           32.3.20   GetHostName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1576

           32.3.21   GetLocalTimezone            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1577

           32.3.22   GetTimezoneFile           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1577

           32.3.23   PClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1577

           32.3.24   POpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1578

           32.3.25   ReadTimezoneFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1579

           32.3.26   SeekDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1579

           32.3.27   SelectText      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1579

           32.3.28   Shell    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1580
                                                                 89

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           32.3.29   SigRaise      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1580

           32.3.30   StatFS     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1581

           32.3.31   TellDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1582

           32.3.32   WaitProcess        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1583

           32.3.33   WIFSTOPPED             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1583

           32.3.34   W_EXITCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1583

           32.3.35   W_STOPCODE                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1584


33   Reference for unit 'unixtype'                                                                                    1585

    33.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1585

    33.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1585

           33.2.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1585

           33.2.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1586


34   Reference for unit 'unixutil'                                                                                    1599

    34.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1599

    34.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1599

           34.2.1    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1599

           34.2.2    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1599

    34.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1600

           34.3.1    ArrayStringToPPchar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1600

           34.3.2    Basename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1600

           34.3.3    Dirname       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1601

           34.3.4    EpochToLocal           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1601

           34.3.5    FNMatch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1602

           34.3.6    FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1603

           34.3.7    GetFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1603

           34.3.8    GregorianToJulian           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1604

           34.3.9    JulianToGregorian           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1604

           34.3.10   LocalToEpoch           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1604

           34.3.11   StringToPPChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1605


35   Reference for unit 'video'                                                                                       1607

    35.1   Examples utility unit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607

    35.2   Writing a custom video driver              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1607

    35.3   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1608

    35.4   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1609

           35.4.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1609

           35.4.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1613

           35.4.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1615

    35.5   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1616
                                                                 90

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           35.5.1    ClearScreen        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1616

           35.5.2    DefaultErrorHandler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1617

           35.5.3    DoneVideo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1617

           35.5.4    GetCapabilities        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1617

           35.5.5    GetCursorType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1618

           35.5.6    GetLockScreenCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1619

           35.5.7    GetVideoDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1620

           35.5.8    GetVideoMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1621

           35.5.9    GetVideoModeCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1621

           35.5.10   GetVideoModeData               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1622

           35.5.11   InitVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1623

           35.5.12   LockScreenUpdate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1623

           35.5.13   SetCursorPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1623

           35.5.14   SetCursorType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1624

           35.5.15   SetVideoDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1625

           35.5.16   SetVideoMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1625

           35.5.17   UnlockScreenUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1626

           35.5.18   UpdateScreen         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1626


36   Reference for unit 'wincrt'                                                                                      1627

    36.1   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1627

    36.2   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1627

           36.2.1    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1627

    36.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1627

           36.3.1    delay    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1627

           36.3.2    keypressed      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1627

           36.3.3    nosound       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1628

           36.3.4    readkey       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1628

           36.3.5    sound      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1628

           36.3.6    textmode        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1628


37   Reference for unit 'x86'                                                                                         1629

    37.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1629

    37.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1629

    37.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1629

           37.3.1    fpIOperm        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1629

           37.3.2    fpIoPL     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1630

           37.3.3    ReadPort        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1630

           37.3.4    ReadPortB          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1630

           37.3.5    ReadPortL          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1631

           37.3.6    ReadPortW          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1631



                                                                 91

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           37.3.7    WritePort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1631

           37.3.8    WritePortB         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1632

           37.3.9    WritePortl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1632

           37.3.10   WritePortW         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1632
                                                                 92

____________________________________________________________________________________________________________________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 the Free Pascal Run-Time library (RTL).

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.
0.1         Overview


The Run-Time Library is the basis of all Free Pascal programs.  It contains the basic units
that  most  programs  will  use,  and  are  made  available  on  all  platforms  supported  by  Free
pascal (well, more or less).

There  are  units  for  compatibility  with  the  Turbo  Pascal  Run-Time  library,  and  there  are
units for compatibility with Delphi.

On top of these two sets, there are also a series of units to handle keyboard/mouse and text
screens in a cross-platform way.

Other units include platform specific units that implement the specifics of a platform, these
are usually needed to support the Turbo Pascal or Delphi units.

Units that fall outside the above outline do not belong in the RTL, but should be included
in the packages, or in the FCL.



                                                                 93


Chapter   1


Reference   for   unit   'BaseUnix'
1.1         Used  units
                                   Table 1.1:  Used units by unit 'BaseUnix'


                                                  __Name____________Page_____
                                                    unixtype        1585



1.2         Overview


The BaseUnix unit was implemented by Marco Van de Voort.  It contains basic unix function-
ality.  It supersedes the Linux unit of version 1.0.X of the compiler, but does not implement
all functionality of the linux unit.

People  that  have  code  which  heavily  uses  the  old  Linux  unit,  can  simply  change  linux  by
oldlinux in the uses clause of their projects, but they should really consider moving to the
Unix and BaseUnix units.

For porting FPC to new unix-like platforms, it should be sufficient to implement the func-
tionality in this unit for the new platform.
1.3         Constants,  types  and  variables



1.3.1        Constants

ARG_MAX  =  UnixType.ARG_MAX


Maximum number of arguments to a program.


BITSINWORD  =  8  *  sizeof  (  cuLong  )


Number of bits in a word.


ESysE2BIG  =  7



                                                              94

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Argument list too long


ESysEACCES  =  13


System error:  Permission denied


ESysEADDRINUSE  =  98


System error:  Address already in use


ESysEADDRNOTAVAIL  =  99


System error:  Cannot assign requested address


ESysEADV  =  68


System error:  Advertise error


ESysEAFNOSUPPORT  =  97


System error:  Address family not supported by protocol


ESysEAGAIN  =  11


System error:  Try again


ESysEALREADY  =  114


System error:  Operation already in progress


ESysEBADE  =  52


System error:  Invalid exchange


ESysEBADF  =  9


System error:  Bad file number


ESysEBADFD  =  77


System error:  File descriptor in bad state


ESysEBADMSG  =  74


System error:  Not a data message


ESysEBADR  =  53


System error:  Invalid request descriptor


ESysEBADRQC  =  56



                                                                 95

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Invalid request code


ESysEBADSLT  =  57


System error:  Invalid slot


ESysEBFONT  =  59


System error:  Bad font file format


ESysEBUSY  =  16


System error:  Device or resource busy


ESysECHILD  =  10


System error:  No child processes


ESysECHRNG  =  44


System error:  Channel number out of range


ESysECOMM  =  70


System error:  Communication error on send


ESysECONNABORTED  =  103


System error:  Software caused connection abort


ESysECONNREFUSED  =  111


System error:  Connection refused


ESysECONNRESET  =  104


System error:  Connection reset by peer


ESysEDEADLK  =  35


System error:  Resource deadlock would occur


ESysEDEADLOCK  =  58


System error:  File locking deadlock error


ESysEDESTADDRREQ  =  89


System error:  Destination address required


ESysEDOM  =  33



                                                                 96

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Math argument out of domain of func


ESysEDOTDOT  =  73


System error:  RFS specific error


ESysEDQUOT  =  122


System error:  Quota exceeded


ESysEEXIST  =  17


System error:  File exists


ESysEFAULT  =  14


System error:  Bad address


ESysEFBIG  =  27


System error:  File too large


ESysEHOSTDOWN  =  112


System error:  Host is down


ESysEHOSTUNREACH  =  113


System error:  No route to host


ESysEIDRM  =  43


System error:  Identifier removed


ESysEILSEQ  =  84


System error:  Illegal byte sequence


ESysEINPROGRESS  =  115


System error:  Operation now in progress


ESysEINTR  =  4


System error:  Interrupted system call


ESysEINVAL  =  22


System error:  Invalid argument


ESysEIO  =  5



                                                                 97

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  I/O error


ESysEISCONN  =  106


System error:  Transport endpoint is already connected


ESysEISDIR  =  21


System error:  Is a directory


ESysEISNAM  =  120


System error:  Is a named type file


ESysEL2HLT  =  51


System error:  Level 2 halted


ESysEL2NSYNC  =  45


System error:  Level 2 not synchronized


ESysEL3HLT  =  46


System error:  Level 3 halted


ESysEL3RST  =  47


System error:  Level 3 reset


ESysELIBACC  =  79


System error:  Can not access a needed shared library


ESysELIBBAD  =  80


System error:  Accessing a corrupted shared library


ESysELIBEXEC  =  83


System error:  Cannot exec a shared library directly


ESysELIBMAX  =  82


System error:  Attempting to link in too many shared libraries


ESysELIBSCN  =  81


System error:  .lib section in a.out corrupted


ESysELNRNG  =  48



                                                                 98

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Link number out of range


ESysELOOP  =  40


System error:  Too many symbolic links encountered


ESysEMFILE  =  24


System error:  Too many open files


ESysEMLINK  =  31


System error:  Too many links


ESysEMSGSIZE  =  90


System error:  Message too long


ESysEMULTIHOP  =  72


System error:  Multihop attempted


ESysENAMETOOLONG  =  36


System error:  File name too long


ESysENAVAIL  =  119


System error:  No XENIX semaphores available


ESysENETDOWN  =  100


System error:  Network is down


ESysENETRESET  =  102


System error:  Network dropped connection because of reset


ESysENETUNREACH  =  101


System error:  Network is unreachable


ESysENFILE  =  23


System error:  File table overflow


ESysENOANO  =  55


System error:  No anode


ESysENOBUFS  =  105



                                                                 99

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  No buffer space available


ESysENOCSI  =  50


System error:  No CSI structure available


ESysENODATA  =  61


System error:  No data available


ESysENODEV  =  19


System error:  No such device


ESysENOENT  =  2


System error:  No such file or directory


ESysENOEXEC  =  8


System error:  Exec format error


ESysENOLCK  =  37


System error:  No record locks available


ESysENOLINK  =  67


System error:  Link has been severed


ESysENOMEM  =  12


System error:  Out of memory


ESysENOMSG  =  42


System error:  No message of desired type


ESysENONET  =  64


System error:  Machine is not on the network


ESysENOPKG  =  65


System error:  Package not installed


ESysENOPROTOOPT  =  92


System error:  Protocol not available


ESysENOSPC  =  28



                                                                 100

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  No space left on device


ESysENOSR  =  63


System error:  Out of streams resources


ESysENOSTR  =  60


System error:  Device not a stream


ESysENOSYS  =  38


System error:  Function not implemented


ESysENOTBLK  =  15


System error:  Block device required


ESysENOTCONN  =  107


System error:  Transport endpoint is not connected


ESysENOTDIR  =  20


System error:  Not a directory


ESysENOTEMPTY  =  39


System error:  Directory not empty


ESysENOTNAM  =  118


System error:  Not a XENIX named type file


ESysENOTSOCK  =  88


System error:  Socket operation on non-socket


ESysENOTTY  =  25


System error:  Not a typewriter


ESysENOTUNIQ  =  76


System error:  Name not unique on network


ESysENXIO  =  6


System error:  No such device or address


ESysEOPNOTSUPP  =  95



                                                                 101

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Operation not supported on transport endpoint


ESysEOVERFLOW  =  75


System error:  Value too large for defined data type


ESysEPERM  =  1


System error:  Operation not permitted.


ESysEPFNOSUPPORT  =  96


System error:  Protocol family not supported


ESysEPIPE  =  32


System error:  Broken pipe


ESysEPROTO  =  71


System error:  Protocol error


ESysEPROTONOSUPPORT  =  93


System error:  Protocol not supported


ESysEPROTOTYPE  =  91


System error:  Protocol wrong type for socket


ESysERANGE  =  34


System error:  Math result not representable


ESysEREMCHG  =  78


System error:  Remote address changed


ESysEREMOTE  =  66


System error:  Object is remote


ESysEREMOTEIO  =  121


System error:  Remote I/O error


ESysERESTART  =  85


System error:  Interrupted system call should be restarted


ESysEROFS  =  30



                                                                 102

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Read-only file system


ESysESHUTDOWN  =  108


System error:  Cannot send after transport endpoint shutdown


ESysESOCKTNOSUPPORT  =  94


System error:  Socket type not supported


ESysESPIPE  =  29


System error:  Illegal seek


ESysESRCH  =  3


System error:  No such process


ESysESRMNT  =  69


System error:  Srmount error


ESysESTALE  =  116


System error:  Stale NFS file handle


ESysESTRPIPE  =  86


System error:  Streams pipe error


ESysETIME  =  62


System error:  Timer expired


ESysETIMEDOUT  =  110


System error:  Connection timed out


ESysETOOMANYREFS  =  109


System error:  Too many references:  cannot splice


ESysETXTBSY  =  26


System error:  Text (code segment) file busy


ESysEUCLEAN  =  117


System error:  Structure needs cleaning


ESysEUNATCH  =  49



                                                                 103

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
System error:  Protocol driver not attached


ESysEUSERS  =  87


System error:  Too many users


ESysEWOULDBLOCK  =  ESysEAGAIN


System error:  Operation would block


ESysEXDEV  =  18


System error:  Cross-device link


ESysEXFULL  =  54


System error:  Exchange full


FD_MAXFDSET  =  1024


Maximum elements in a TFDSet (126  ) array.


FPE_FLTDIV  =  3


Value signalling floating point divide by zero in case of SIGFPE signal


FPE_FLTINV  =  7


Value signalling floating point invalid operation in case of SIGFPE signal


FPE_FLTOVF  =  4


Value signalling floating point overflow in case of SIGFPE signal


FPE_FLTRES  =  6


Value signalling floating point inexact result in case of SIGFPE signal


FPE_FLTSUB  =  8


Value signalling floating point subscript out of range in case of SIGFPE signal


FPE_FLTUND  =  5


Value signalling floating point underflow in case of SIGFPE signal


FPE_INTDIV  =  1


Value signalling integer divide in case of SIGFPE signal


FPE_INTOVF  =  2



                                                                 104

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Value signalling integer overflow in case of SIGFPE signal


F_GetFd  =  1


fpFCntl (141  ) command:  Get close-on-exec flag


F_GetFl  =  3


fpFCntl (141  ) command:  Get filedescriptor flags


F_GetLk  =  5


fpFCntl (141  ) command:  Get lock


F_GetOwn  =  9


fpFCntl (141  ) command:  get owner of filedescriptor events


F_OK  =  0


fpAccess (132  ) call test:  file exists.


F_SetFd  =  2


fpFCntl (141  ) command:  Set close-on-exec flag


F_SetFl  =  4


fpFCntl (141  ) command:  Set filedescriptor flags


F_SetLk  =  6


fpFCntl (141  ) command:  Set lock


F_SetLkW  =  7


fpFCntl (141  ) command:  Test lock


F_SetOwn  =  8


fpFCntl (141  ) command:  Set owner of filedescriptor events


ln2bitmask  =  1  shl  ln2bitsinword  -  1


Last bit in word.


MAP_ANON  =  MAP_ANONYMOUS


Anonymous memory mapping (data private to application)


MAP_ANONYMOUS  =  $20



                                                                 105

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
FpMMap (154  ) map type:  Don't use a file


MAP_FAILED  =  pointer  (  -  1  )


Memory mapping failed error code


MAP_FIXED  =  $10


FpMMap (154  ) map type:  Interpret addr exactly


MAP_PRIVATE  =  $2


FpMMap (154  ) map type:  Changes are private


MAP_SHARED  =  $1


FpMMap (154  ) map type:  Share changes


MAP_TYPE  =  $f


FpMMap (154  ) map type:  Bitmask for type of mapping


NAME_MAX  =  UnixType.NAME_MAX


Maximum filename length.


O_APPEND  =  $400


fpOpen (157  ) file open mode:  Append to file


O_CREAT  =  $40


fpOpen (157  ) file open mode:  Create if file does not yet exist.


O_DIRECT  =  $4000


fpOpen (157  ) file open mode:  Minimize caching effects


O_DIRECTORY  =  $10000


fpOpen (157  ) file open mode:  File must be directory.


O_EXCL  =  $80


fpOpen (157  ) file open mode:  Open exclusively


O_NDELAY  =  O_NONBLOCK


fpOpen (157  ) file open mode:  Alias for O_NonBlock (107  )


O_NOCTTY  =  $100



                                                                 106

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
fpOpen (157  ) file open mode:  No TTY control.


O_NOFOLLOW  =  $20000


fpOpen (157  ) file open mode:  Fail if file is symbolic link.


O_NONBLOCK  =  $800


fpOpen (157  ) file open mode:  Open in non-blocking mode


O_RDONLY  =  0


fpOpen (157  ) file open mode:  Read only


O_RDWR  =  2


fpOpen (157  ) file open mode:  Read/Write


O_SYNC  =  $1000


fpOpen (157  ) file open mode:  Write to disc at once


O_TRUNC  =  $200


fpOpen (157  ) file open mode:  Truncate file to length 0


O_WRONLY  =  1


fpOpen (157  ) file open mode:  Write only


PATH_MAX  =  UnixType.PATH_MAX


Maximum pathname length.


PRIO_PGRP  =  UnixType.PRIO_PGRP


Easy access alias for unixtype.PRIO_PGRP (1585   )


PRIO_PROCESS  =  UnixType.PRIO_PROCESS


Easy access alias for unixtype.PRIO_PROCESS (1585   )


PRIO_USER  =  UnixType.PRIO_USER


Easy access alias for unixtype.PRIO_USER (1585   )


PROT_EXEC  =  $4


FpMMap (154  ) memory access:  page can be executed


PROT_NONE  =  $0



                                                                 107

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
FpMMap (154  ) memory access:  page can not be accessed


PROT_READ  =  $1


FpMMap (154  ) memory access:  page can be read


PROT_WRITE  =  $2


FpMMap (154  ) memory access:  page can be written


RLIMIT_AS  =  9


RLimit request address space limit


RLIMIT_CORE  =  4


RLimit request max core file size


RLIMIT_CPU  =  0


RLimit request CPU time in ms


RLIMIT_DATA  =  2


RLimit request max data size


RLIMIT_FSIZE  =  1


Rlimit request maximum filesize


RLIMIT_LOCKS  =  10


RLimit request maximum file locks held


RLIMIT_MEMLOCK  =  8


RLimit request max locked-in-memory address space


RLIMIT_NOFILE  =  7


RLimit request max number of open files


RLIMIT_NPROC  =  6


RLimit request max number of processes


RLIMIT_RSS  =  5


RLimit request max resident set size


RLIMIT_STACK  =  3



                                                                 108

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
RLimit request max stack size


R_OK  =  4


fpAccess (132  ) call test:  read allowed


SA_INTERRUPT  =  $20000000


Sigaction options:  ?


SA_NOCLDSTOP  =  1


Sigaction options:  Do not receive notification when child processes stop


SA_NOCLDWAIT  =  2


Sigaction options:  ?


SA_NODEFER  =  $40000000


Sigaction options:  Do not mask signal in its own signal handler


SA_NOMASK  =  SA_NODEFER


Sigaction options:  Do not prevent the signal from being received when it is handled.


SA_ONESHOT  =  SA_RESETHAND


Sigaction options:  Restore the signal action to the default state.


SA_ONSTACK  =  $08000000


SA_ONSTACK is used in the fpsigaction (169  ) to indicate the signal handler must be called on
an alternate signal stack provided by fpsigaltstack (94 ).  If an alternate stack is not available,
the default stack will be used.


SA_RESETHAND  =  $80000000


Sigaction options:  Restore signal action to default state when signal handler exits.


SA_RESTART  =  $10000000


Sigaction options:  Provide behaviour compatible with BSD signal semantics


SA_RESTORER  =  $04000000


Signal restorer handler


SA_SIGINFO  =  4


Sigaction options:  The signal handler takes 3 arguments, not one.



                                                                 109

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
SEEK_CUR  =  1


fpLSeek (151  ) option:  Set position relative to current position.


SEEK_END  =  2


fpLSeek (151  ) option:  Set position relative to end of file.


SEEK_SET  =  0


fpLSeek (151  ) option:  Set absolute position.


SIGABRT  =  6


Signal:  ABRT (Abort)


SIGALRM  =  14


Signal:  ALRM (Alarm clock)


SIGBUS  =  7


Signal:  BUS (bus error)


SIGCHLD  =  17


Signal:  CHLD (child status changed)


SIGCONT  =  18


Signal:  CONT (Continue)


SIGFPE  =  8


Signal:  FPE (Floating point error)


SIGHUP  =  1


Signal:  HUP (Hangup)


SIGILL  =  4


Signal:  ILL (Illegal instruction)


SIGINT  =  2


Signal:  INT (Interrupt)


SIGIO  =  29


Signal:  IO (I/O operation possible)



                                                                 110

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
SIGIOT  =  6


Signal:  IOT (IOT trap)


SIGKILL  =  9


Signal:  KILL (unblockable)


SIGPIPE  =  13


Signal:  PIPE (Broken pipe


SIGPOLL  =  SIGIO


Signal:  POLL (Pollable event)


SIGPROF  =  27


Signal:  PROF (Profiling alarm)


SIGPWR  =  30


Signal:  PWR (power failure restart)


SIGQUIT  =  3


Signal:  QUIT


SIGSEGV  =  11


Signal:  SEGV (Segmentation violation)


SIGSTKFLT  =  16


Signal:  STKFLT (Stack Fault)


SIGSTOP  =  19


Signal:  STOP (Stop, unblockable)


SIGTerm  =  15


Signal:  TERM (Terminate)


SIGTRAP  =  5


Signal:  TRAP (Trace trap)


SIGTSTP  =  20


Signal:  TSTP (keyboard stop)



                                                                 111

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
SIGTTIN  =  21


Signal:  TTIN (Terminal input, background)


SIGTTOU  =  22


Signal:  TTOU (Terminal output, background)


SIGUNUSED  =  31


Signal:  Unused


SIGURG  =  23


Signal:  URG (Socket urgent condition)


SIGUSR1  =  10


Signal:  USR1 (User-defined signal 1)


SIGUSR2  =  12


Signal:  USR2 (User-defined signal 2)


SIGVTALRM  =  26


Signal:  VTALRM (Virtual alarm clock)


SIGWINCH  =  28


Signal:  WINCH (Window/Terminal size change)


SIGXCPU  =  24


Signal:  XCPU (CPU limit exceeded)


SIGXFSZ  =  25


Signal:  XFSZ (File size limit exceeded)


SIG_BLOCK  =  0


Sigprocmask flags:  Add signals to the set of blocked signals.


SIG_DFL  =  0


Signal handler:  Default signal handler


SIG_ERR  =  -1


Signal handler:  error



                                                                 112

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
SIG_IGN  =  1


Signal handler:  Ignore signal


SIG_MAXSIG  =  UnixType.SIG_MAXSIG


Maximum system signal number.


SIG_SETMASK  =  2


Sigprocmask flags:  Set of blocked signals is given.


SIG_UNBLOCK  =  1


Sigprocmask flags:  Remove signals from the set set of blocked signals.


SI_PAD_SIZE  =  (  (  128  div  sizeof  (  longint  )  )  -  3  )


Signal information pad size.


SYS_NMLN  =  UnixType.SYS_NMLN


Max system name length.


S_IFBLK  =  24576


File (#rtl.baseunix.stat (126  ) record) mode:  Block device


S_IFCHR  =  8192


File (#rtl.baseunix.stat (126  ) record) mode:  Character device


S_IFDIR  =  16384


File (#rtl.baseunix.stat (126  ) record) mode:  Directory


S_IFIFO  =  4096


File (#rtl.baseunix.stat (126  ) record) mode:  FIFO


S_IFLNK  =  40960


File (#rtl.baseunix.stat (126  ) record) mode:  Link


S_IFMT  =  61440


File (#rtl.baseunix.stat (126  ) record) mode:  File type bit mask


S_IFREG  =  32768


File (#rtl.baseunix.stat (126  ) record) mode:  Regular file



                                                                 113

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
S_IFSOCK  =  49152


File (#rtl.baseunix.stat (126  ) record) mode:  Socket


S_IRGRP  =  %0000100000


Mode flag:  Read by group.


S_IROTH  =  %0000000100


Mode flag:  Read by others.


S_IRUSR  =  %0100000000


Mode flag:  Read by owner.


S_IRWXU  =  S_IRUSR  or  S_IWUSR  or  S_IXUSR


Mode flag:  Read, write, execute by user.


S_IWGRP  =  %0000010000


Mode flag:  Write by group.


S_IWOTH  =  %0000000010


Mode flag:  Write by others.


S_IWUSR  =  %0010000000


Mode flag:  Write by owner.


S_IXGRP  =  %0000001000


Mode flag:  Execute by group.


S_IXOTH  =  %0000000001


Mode flag:  Execute by others.


S_IXUSR  =  %0001000000


Mode flag:  Execute by owner.


UTSNAME_DOMAIN_LENGTH  =  UTSNAME_LENGTH


Max length of utsname (131  ) domain name.


UTSNAME_LENGTH  =  SYS_NMLN


Max length of utsname (131  ) system name, release, version, machine.



                                                                 114

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
UTSNAME_NODENAME_LENGTH  =  UTSNAME_LENGTH


Max length of utsname (131  ) node name.


WNOHANG  =  1


#rtl.baseunix.fpWaitpid (181  ) option:  Do not wait for processes to terminate.


wordsinfdset  =  FD_MAXFDSET  div  BITSINWORD


Number of words in a TFDSet (126  ) array


wordsinsigset  =  SIG_MAXSIG  div  BITSINWORD


Number of words in a signal set.


WUNTRACED  =  2


#rtl.baseunix.fpWaitpid (181  ) option:  Also report children wich were stopped but not yet
reported


W_OK  =  2


fpAccess (132  ) call test:  write allowed


X_OK  =  1


fpAccess (132  ) call test:  execute allowed


_STAT_VER  =  _STAT_VER_LINUX


Stat version number


_STAT_VER_KERNEL  =  1


Current version of stat record


_STAT_VER_LINUX  =  3


Version of linux stat record


_STAT_VER_LINUX_OLD  =  1


Old kernel definition of stat


_STAT_VER_SVR4  =  2


SVR 4 definition of stat


                                                                 115

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
1.3.2        Types

Blkcnt64_t  =  cuint64


64-bit block count


Blkcnt_t  =  cuint


Block count type.


Blksize_t  =  cuint


Block size type.


cbool  =  UnixType.cbool


Boolean type


cchar  =  UnixType.cchar


Alias for #rtl.UnixType.cchar (1587   )


cdouble  =  UnixType.cdouble


Double precision real format.


cfloat  =  UnixType.cfloat


Floating-point real format


cint  =  UnixType.cint


C type:  integer (natural size)


cint16  =  UnixType.cint16


C type:  16 bits sized, signed integer.


cint32  =  UnixType.cint32


C type:  32 bits sized, signed integer.


cint64  =  UnixType.cint64


C type:  64 bits sized, signed integer.


cint8  =  UnixType.cint8


C type:  8 bits sized, signed integer.


clock_t  =  UnixType.clock_t



                                                                 116

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Clock ticks type


clong  =  UnixType.clong


C type:  long signed integer (double sized)


clongdouble  =  UnixType.clongdouble


Usually translates to an extended, but is CPU dependent.


clonglong  =  UnixType.clonglong


C type:  64-bit (double long) signed integer.


cschar  =  UnixType.cschar


Signed character type


cshort  =  UnixType.cshort


C type:  short signed integer (half sized)


csigned  =  UnixType.csigned


csigned is an alias for cint (116  ).


csint  =  UnixType.csint


Signed integer


cslong  =  UnixType.cslong


The size is CPU dependent.


cslonglong  =  UnixType.cslonglong


cslonglong is an alias for clonglong (117  ).


csshort  =  UnixType.csshort


Short signed integer type


cuchar  =  UnixType.cuchar


Alias for #rtl.UnixType.cuchar (1588   )


cuint  =  UnixType.cuint


C type:  unsigned integer (natural size)


cuint16  =  UnixType.cuint16



                                                                 117

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
C type:  16 bits sized, unsigned integer.


cuint32  =  UnixType.cuint32


C type:  32 bits sized, unsigned integer.


cuint64  =  UnixType.cuint64


C type:  64 bits sized, unsigned integer.


cuint8  =  UnixType.cuint8


C type:  8 bits sized, unsigned integer.


culong  =  UnixType.culong


C type:  long unsigned integer (double sized)


culonglong  =  UnixType.culonglong


C type:  64-bit (double long) unsigned integer.


cunsigned  =  UnixType.cunsigned


Alias for #rtl.unixtype.cunsigned (1589   )


cushort  =  UnixType.cushort


C type:  short unsigned integer (half sized)


dev_t  =  UnixType.dev_t


Device descriptor type.


Dir  =  record
   dd_fd  :  Integer;
   dd_loc  :  LongInt;
   dd_size  :  Integer;
   dd_buf  :  pDirent;
   dd_nextoff  :  cardinal;
   dd_max  :  Integer;
   dd_lock  :  pointer;
end
Record used in fpOpenDir (158  ) and fpReadDir (162  ) calls


Dirent  =  packed  record
   d_fileno  :  ino64_t;
   d_off  :  off_t;
   d_reclen  :  cushort;
   d_type  :  cuchar;
   d_name  :  Array[0..(255+1)-1]  of  Char;
end

                                                                 118

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Record used in the fpReadDir (162  ) function to return files in a directory.


FLock  =  record
   l_type  :  cshort;
   l_whence  :  cshort;
   l_start  :  off_t;
   l_len  :  off_t;
   l_pid  :  pid_t;
end
Lock description type for fpFCntl (141  ) lock call.


gid_t  =  UnixType.gid_t


Group ID type.


ino_t  =  UnixType.ino_t


Inode type.


iovec  =  record
   iov_base  :  pointer;
   iov_len  :  size_t;
end
iovec is used in fpreadv (164  ) for IO to multiple buffers to describe a buffer location.


mode_t  =  UnixType.mode_t


Inode mode type.


nlink_t  =  UnixType.nlink_t


Number of links type.


off_t  =  UnixType.off_t


Offset type.


PBlkCnt  =  ^Blkcnt_t


pointer to TBlkCnt (126  ) type.


PBlkSize  =  ^Blksize_t


Pointer to TBlkSize (126  ) type.


pcbool  =  UnixType.pcbool
                                                                 119

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Pointer to boolean type cbool (116  )


pcchar  =  UnixType.pcchar


Alias for #rtl.UnixType.pcchar (1590   )


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (116  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (116  ) type.


pcint  =  UnixType.pcint


Pointer to cInt (116  ) type.


pcint16  =  UnixType.pcint16


Pointer to 16-bit signed integer type


pcint32  =  UnixType.pcint32


Pointer to signed 32-bit integer type


pcint64  =  UnixType.pcint64


Pointer to signed 64-bit integer type


pcint8  =  UnixType.pcint8


Pointer to 8-bits signed integer type


pClock  =  UnixType.pClock


Pointer to TClock (126  ) type.


pclong  =  UnixType.pclong


Pointer to cLong (117  ) type.


pclongdouble  =  UnixType.pclongdouble


Pointer to the long double type clongdouble (117  )


pclonglong  =  UnixType.pclonglong


Pointer to longlong type.


pcschar  =  UnixType.pcschar



                                                                 120

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Pointer to character type cschar (117  ).


pcshort  =  UnixType.pcshort


Pointer to cShort (117  ) type.


pcsigned  =  UnixType.pcsigned


Pointer to signed integer type csigned (117  ).


pcsint  =  UnixType.pcsint


Pointer to signed integer type csint (117  )


pcslong  =  UnixType.pcslong


Pointer ot the signed long cslong (117  )


pcslonglong  =  UnixType.pcslonglong


Pointer to Signed longlong type cslonglong (117  )


pcsshort  =  UnixType.pcsshort


Pointer to short signed integer type csshort (117  )


pcuchar  =  UnixType.pcuchar


Alias for #rtl.UnixType.pcuchar (1591   )


pcuint  =  UnixType.pcuint


Pointer to cUInt (117  ) type.


pcuint16  =  UnixType.pcuint16


Pointer to 16-bit unsigned integer type


pcuint32  =  UnixType.pcuint32


Pointer to unsigned 32-bit integer type


pcuint64  =  UnixType.pcuint64


Pointer to unsigned 64-bit integer type


pcuint8  =  UnixType.pcuint8


Pointer to 8-bits unsigned integer type


pculong  =  UnixType.pculong



                                                                 121

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Pointer to cuLong (118  ) type.


pculonglong  =  UnixType.pculonglong


Unsigned longlong type


pcunsigned  =  UnixType.pcunsigned


Alias for #rtl.unixtype.pcunsigned (1592   )


pcushort  =  UnixType.pcushort


Pointer to cuShort (118  ) type.


pDev  =  UnixType.pDev


Pointer to TDev (126  ) type.


pDir  =  ^Dir


Pointer to TDir (126  ) record


pDirent  =  ^Dirent


Pointer to TDirent (126  ) record.


pFDSet  =  ^TFDSet


Pointer to TFDSet (126  ) type.


pFilDes  =  ^TFilDes


Pointer to TFilDes (126  ) type.


pfpstate  =  ^tfpstate


Pointer to tfpstate (127  ) record.


pGid  =  UnixType.pGid


Pointer to TGid (127  ) type.


pGrpArr  =  ^TGrpArr


Pointer to TGrpArr (127  ) array.


pid_t  =  UnixType.pid_t


Process ID type.


pIno  =  UnixType.pIno



                                                                 122

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Pointer to TIno (128  ) type.


piovec  =  ^tiovec


pointer to a iovec (119  ) record


pMode  =  UnixType.pMode


Pointer to TMode (128  ) type.


pnLink  =  UnixType.pnLink


Pointer to TnLink (128  ) type.


pOff  =  UnixType.pOff


Pointer to TOff (128  ) type.


pPid  =  UnixType.pPid


Pointer to TPid (128  ) type.


PRLimit  =  ^TRLimit


Pointer to TRLimit (128  ) record


psigactionrec  =  ^sigactionrec


Pointer to SigActionRec (125  ) record type.


PSigContext  =  ^TSigContext


Pointer to #rtl.baseunix.TSigContext (129  ) record type.


psiginfo  =  ^tsiginfo


Pointer to #rtl.baseunix.TSigInfo (129  ) record type.


psigset  =  ^tsigset


Pointer to SigSet (125  ) type.


pSize  =  UnixType.pSize


Pointer to TSize (130  ) type.


pSocklen  =  UnixType.pSocklen


Pointer to TSockLen (130  ) type.


psSize  =  UnixType.psSize



                                                                 123

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Pointer to TsSize (130  ) type


PStat  =  ^Stat


Pointer to TStat (130  ) type.


pthread_cond_t  =  UnixType.pthread_cond_t


Thread conditional variable type.


pthread_mutex_t  =  UnixType.pthread_mutex_t


Thread mutex type.


pthread_t  =  UnixType.pthread_t


Posix thread type.


pTime  =  UnixType.pTime


Pointer to TTime (130  ) type.


ptimespec  =  UnixType.ptimespec


Pointer to timespec (127  ) type.


ptimeval  =  UnixType.ptimeval


Pointer to timeval (127  ) type.


ptimezone  =  ^timezone


Pointer to TimeZone (127  ) record.


ptime_t  =  UnixType.ptime_t


Pointer to time_t (127  ) type.


PTms  =  ^tms


Pointer to TTms (130  ) type.


Pucontext  =  ^Tucontext


Pointer to TUContext (131  ) type.


pUid  =  UnixType.pUid


Pointer to TUid (131  ) type.


pUtimBuf  =  ^UTimBuf



                                                                 124

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Pointer to TUTimBuf (131  ) type.


PUtsName  =  ^TUtsName


Pointer to TUtsName (131  ) type.


rlim_t  =  culong


rlim_t is used as the type for the various fields in the TRLimit (128  ) record.


sigactionhandler  =  sigactionhandler_t


When installing a signal handler, the actual signal handler must be of type SigActionHandler.


sigactionhandler_t  =  procedure(signal:  LongInt;info:  psiginfo;
                                                   context:  PSigContext)


Standard signal action handler prototype


sigactionrec  =  record
   sa_handler  :  sigactionhandler_t;
   sa_flags  :  culong;
   sa_restorer  :  sigrestorerhandler_t;
   sa_mask  :  sigset_t;
end
Record used in fpSigAction (169  ) call.


signalhandler  =  signalhandler_t


Simple signal handler prototype


signalhandler_t  =  procedure(signal:  LongInt)


Standard signal handler prototype


sigrestorerhandler  =  sigrestorerhandler_t


Alias for sigrestorerhandler_t (125  ) type.


sigrestorerhandler_t  =  procedure


Standard signal action restorer prototype


sigset  =  sigset_t


Signal set type


sigset_t  =  Array[0..wordsinsigset-1]  of  culong



                                                                 125

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Signal set type


size_t  =  UnixType.size_t


Size specification type.


socklen_t  =  UnixType.socklen_t


Socket address length type.


ssize_t  =  UnixType.ssize_t


Small size type.


Stat  =  packed  record
end
Record describing an inode (file) in the FPFstat (143  ) call.


TBlkCnt  =  Blkcnt_t


Alias for Blkcnt_t (116  ) type.


TBlkSize  =  Blksize_t


Alias for blksize_t (116  ) type.


TClock  =  UnixType.TClock


Alias for clock_t (117  ) type.


TDev  =  UnixType.TDev


Alias for dev_t (118  ) type.


TDir  =  Dir


Alias for Dir (118  ) type.


TDirent  =  Dirent


Alias for Dirent (119  ) type.


TFDSet  =  Array[0..(FD_MAXFDSETdivBITSINWORD)-1]  of  culong


File descriptor set for fpSelect (165  ) call.


TFilDes  =  Array[0..1]  of  cint


Array of file descriptors as used in fpPipe (160  ) call.



                                                                 126

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
tfpreg  =  record
   significand  :  Array[0..3]  of  Word;
   exponent  :  Word;
end
Record describing floating point register in signal handler.


tfpstate  =  record
   cw  :  cardinal;
   sw  :  cardinal;
   tag  :  cardinal;
   ipoff  :  cardinal;
   cssel  :  cardinal;
   dataoff  :  cardinal;
   datasel  :  cardinal;
   st  :  Array[0..7]  of  tfpreg;
   status  :  cardinal;
end
Record describing floating point unit in signal handler.


TGid  =  UnixType.TGid


Alias for gid_t (119  ) type.


TGrpArr  =  Array[0..0]  of  TGid


Array of gid_t (119  ) IDs


timespec  =  UnixType.timespec


Short time specification type.


timeval  =  UnixType.timeval


Time specification type.


timezone  =  packed  record
   tz_minuteswest  :  cint;
   tz_dsttime  :  cint;
end
Record describing a timezone


time_t  =  UnixType.time_t


Time span type


TIno  =  UnixType.TIno



                                                                 127

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Alias for ino_t (119  ) type.


TIOCtlRequest  =  UnixType.TIOCtlRequest


Easy access alias for unixtype.TIOCtlRequest (1597   )


tiovec  =  iovec


Alias for the iovec (119  ) record type.


TMode  =  UnixType.TMode


Alias for mode_t (119  ) type.


tms  =  packed  record
   tms_utime  :  clock_t;
   tms_stime  :  clock_t;
   tms_cutime  :  clock_t;
   tms_cstime  :  clock_t;
end
Record containing timings for fpTimes (178  ) call.


TnLink  =  UnixType.TnLink


Alias for nlink_t (119  ) type.


TOff  =  UnixType.TOff


Alias for off_t (119  ) type.


TPid  =  UnixType.TPid


Alias for pid_t (122  ) type.


TRLimit  =  record
   rlim_cur  :  rlim_t;
   rlim_max  :  rlim_t;
end
TRLimit is the structure used by the kernel to return resource limit information in.


tsigactionhandler  =  sigactionhandler_t


Alias for sigactionhandler_t (125  ) type.


tsigaltstack  =  record
   ss_sp  :  pointer;
   ss_flags  :  LongInt;
   ss_size  :  LongInt;
end

                                                                 128

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Provide the location of an alternate signal handler stack.


TSigContext  =  record
   gs  :  Word;
   __gsh  :  Word;
   fs  :  Word;
   __fsh  :  Word;
   es  :  Word;
   __esh  :  Word;
   ds  :  Word;
   __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  :  Word;
   __csh  :  Word;
   eflags  :  cardinal;
   esp_at_signal  :  cardinal;
   ss  :  Word;
   __ssh  :  Word;
   fpstate  :  pfpstate;
   oldmask  :  cardinal;
   cr2  :  cardinal;
end
This type is CPU dependent.  Cross-platform code should not use the contents of this record.


tsiginfo  =  record
   si_signo  :  LongInt;
   si_errno  :  LongInt;
   si_code  :  LongInt;
   _sifields  :  record
   end;
end
This type describes the signal that occurred.


tsignalhandler  =  signalhandler_t


Alias for signalhandler_t (125  ) type.


tsigrestorerhandler  =  sigrestorerhandler_t
                                                                 129

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___
Alias for sigrestorerhandler_t (125  ) type.


tsigset  =  sigset_t


Alias for SigSet (125  ) type.


TSize  =  UnixType.TSize


Alias for size_t (126  ) type


TSocklen  =  UnixType.TSocklen


Alias for socklen_t (126  ) type.


TsSize  =  UnixType.TsSize


Alias for ssize_t (126  ) type


TStat  =  Stat


Alias for Stat (126  ) type.


tstatfs  =  UnixType.TStatFs


Record describing a file system in the baseunix.fpstatfs (94 ) call.


TTime  =  UnixType.TTime


Alias for TTime (130  ) type.


Ttimespec  =  UnixType.Ttimespec


Alias for TimeSpec (127  ) type.


TTimeVal  =  UnixType.TTimeVal


Alias for timeval (127  ) type.


TTimeZone  =  timezone


Alias for TimeZone (127  ) record.


TTms  =  tms


Alias for Tms (128  ) record type.


TUcontext  =  record
   uc_flags  :  cardinal;
   uc_link  :  Pucontext;
   uc_stack  :  tsigaltstack;
   uc_mcontext  :  TSigContext;
   uc_sigmask  :  tsigset;
end

                                                                 130

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                This structure is used to describe the user context in a program or thread.  It is not used in
                this unit, but is provided for completeness.


                TUid  =  UnixType.TUid


                Alias for uid_t (131  ) type.


                TUtimBuf  =  UTimBuf


                Alias for UtimBuf (131  ) type.


                TUtsName  =  UtsName


                Alias for UtsName (131  ) type.


                uid_t  =  UnixType.uid_t


                User ID type


                UTimBuf  =  record
                   actime  :  time_t;
                   modtime  :  time_t;
                end



                Record used in fpUtime (180  ) to set file access and modificaton times.


                UtsName  =  record
                   Sysname  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
                   Nodename  :  Array[0..UTSNAME_NODENAME_LENGTH-1]  of  Char;
                   Release  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
                   Version  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
                   Machine  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
                   Domain  :  Array[0..UTSNAME_DOMAIN_LENGTH-1]  of  Char;
                end



                The  elements  of  this  record  are  null-terminated  C  style  strings,  you  cannot  access  them
                directly.
                1.4         Procedures  and  functions



                1.4.1        CreateShellArgV

    Synopsis:    Create a null-terminated array of strings from a command-line string

Declaration:     function  CreateShellArgV(const  prog:  String)  :  ppchar
                function  CreateShellArgV(const  prog:  Ansistring)  :  ppchar

    Visibility:   default

Description:     CreateShellArgV creates a command-line string for executing a shell command using 'sh -
                c'.  The result is a null-terminated array of null-terminated strings suitable for use in fpExecv
                (138  ) and friends.

       Errors:   If no more memory is available, a heap error may occur.

    See also:    fpExecv (138  ), FreeShellArgV (183  )



                                                                                 131

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.2        FpAccess

    Synopsis:    Check file access

Declaration:     function  FpAccess(pathname:  pChar;aMode:  cint)  :  cint
                function  FpAccess(pathname:  AnsiString;aMode:  cint)  :  cint

    Visibility:   default

Description:     FpAccess tests user's access rights on the specified file.  Mode is a mask existing of one or
                more of the following:


                R__OK     User has read rights.

                W__OK      User has write rights.

                X__OK     User has execute rights.

                F__OK    File exists.


                The test is done with the real user ID, instead of the effective user ID. If the user has the
                requested rights, zero is returned.  If access is denied, or an error occurred, a nonzero value
                is returned.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                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.

                sys__enomem        Insufficient kernel memory.

                sys__eloop     Path has a circular symbolic link.


    See also:    FpChown (135  ), FpChmod (134  )


                Listing:  ./bunixex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   Program       t o  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     B a s e U n i x;


                 b e g i n
                    i f  f p A c c e s s ( '/ e t c/ p a s s w d' ,W_OK   )=0    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  c a n   w r i t e t o  t h e  / e t c/ p a s s w d f i l e  ! ') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 132

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.3        FpAlarm

    Synopsis:    Schedule an alarm signal to be delivered

Declaration:     function  FpAlarm(seconds:  cuint)  :  cuint

    Visibility:   default

Description:     FpAlarm  schedules  an  alarm  signal  to  be  delivered  to  your  process  in  Seconds  seconds.
                When Seconds seconds have elapsed, the system will send a SIGALRM signal to the current
                process.  If  Seconds is zero, then no new alarm will be set.  Whatever the value of  Seconds,
                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.  A negative value indicates an error.

    See also:    fpSigAction (169  ), fpPause (159  )


                Listing:__./bunixex/ex59.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 9;


                {   Program       t o  d e m o n s t r a t et h e  Alarm      f u n c t i o n. }


                Uses     B a s e U n i x;


                 P r o c e d u r eA l a r m H a n d l e(rS i g  :  c i n t) ; c d e c l;


                 b e g i n
                    W r i t e l n ( 'Got    t o   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') ;
                    f p S i g n a l(SIGALRM     , S i g n a l H a n d l e(r@ 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 gAlarm     i n  1 0   s e c o n d s') ;
                    f p A l a r m( 1 0 ) ;
                    W r i t e l n ( 'P a u s i n g' ) ;
                    f p P a u s e;
                    W r i t e l n ( 'P a u s e  r e t u r n e d') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.4        FpChdir

    Synopsis:    Change current working directory.

Declaration:     function  FpChdir(path:  pChar)  :  cint
                function  FpChdir(path:  AnsiString)  :  cint

    Visibility:   default

Description:     fpChDir sets the current working directory to Path.

                It returns zero if the call was succesful, -1 on error.

                Note:  There exist a portable alterative to fpChDir:  system.chdir.  Please use fpChDir only
                if you are writing Unix specific code.  System.chdir will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    fpGetCwd (144  )



                                                                                 133

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.5        FpChmod

    Synopsis:    Change file permission bits

Declaration:     function  FpChmod(path:  pChar;Mode:  TMode)  :  cint
                function  FpChmod(path:  AnsiString;Mode:  TMode)  :  cint

    Visibility:   default

Description:     fpChmod sets the Mode bits of the file in Path to Mode.  Mode can be specified by 'or'-ing
                the following values:


                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.


                If the function is successful, zero is returned.  A nonzero return value indicates an error.

       Errors:   The following error codes are returned:


                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__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:    fpChown (135  ), fpAccess (132  )


                Listing:  ./bunixex/ex23.pp
                                                                                 134

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 3;


                {   Program       t o  d e m o n s t r a t et h e  Chmod      f u n c t i o n. }


                Uses     B a s e U n i x,U n i x;


                Var    F   :  T e x t ;


                 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/ s h ' ) ;
                    W r i t e l n ( f , 'e c h o Some      t e x t f o r  t h i s  f i l e' ) ;
                    C l o s e ( F ) ;
                    fpChmod       ( ' t e s t e x 2 1', & 7 7 7 ) ;
                    {   F i l e i s  now     e x e c u t a b l e }
                    f p e x e c l ( ' . /t e s t e x 2 1' , [ ] ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.6        FpChown

    Synopsis:    Change owner of file

Declaration:     function  FpChown(path:  pChar;owner:  TUid;group:  TGid)  :  cint
                function  FpChown(path:  AnsiString;owner:  TUid;group:  TGid)  :  cint

    Visibility:   default

Description:     fpChown sets the User ID and Group ID of the file in Path to Owner,Group.

                The function returns zero if the call was succesfull, a nonzero return value indicates an error.

       Errors:   The following error codes are returned:


                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__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:    fpChmod (134  ), fpAccess (132  )


                Listing:  ./bunixex/ex24.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 4;


                {   Program       t o  d e m o n s t r a t et h e  Chown      f u n c t i o n. }


                Uses     B a s e U n i x;
                                                                                 135

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                Var    UID     :  TUid   ;
                       GID     :  TGid   ;
                       F   :  T e x t ;


                 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. ') ;
                    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  fpChown       ( ' t e s t. t x t' ,UID   ,GID  )<>0     then
                        i f  f p g e t e r r n=oESysEPERM        then
                           W r i t e l n ( 'You    a r e  n o t  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  c o d e :   ' ,f p g e t e r r n o)
                    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___.____________________________________________________________________________________________________________*
 *___________

                1.4.7        FpClose

    Synopsis:    Close file descriptor

Declaration:     function  FpClose(fd:  cint)  :  cint

    Visibility:   default

Description:     FpClose closes a file with file descriptor Fd.  The function returns zero if the file was closed
                successfully, a nonzero return value indicates an error.

                For an example, see FpOpen (157  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpOpen (157  ), FpRead (161  ), FpWrite (182  ), FpFTruncate (144  ), FpLSeek (151  )
                1.4.8        FpClosedir

    Synopsis:    Close directory file descriptor

Declaration:     function  FpClosedir(var  dirp:  Dir)  :  cint

    Visibility:   default

Description:     FpCloseDir  closes  the  directory  pointed  to  by  dirp.  It  returns  zero  if  the  directory  was
                closed succesfully, -1 otherwise.

                For an example, see fpOpenDir (158  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpOpenDir (158  ), FpReadDir (162  )


                                                                                 136

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.9        FpDup

    Synopsis:    Duplicate a file handle

Declaration:     function  FpDup(fildes:  cint)  :  cint
                function  FpDup(var  oldfile:  text;var  newfile:  text)  :  cint
                function  FpDup(var  oldfile:  File;var  newfile:  File)  :  cint

    Visibility:   default

Description:     FpDup returns a file descriptor that is a duplicate of the file descriptor fildes.

                The second and third forms make 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, these calls do not have the same functionality as the dup 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 a negative value in case of an error,  a positive value is a file handle,
                and indicates succes.

       Errors:   A negative value can be one of the following error codes:


                sys__ebadf     OldFile hasn't been assigned.

                sys__emfile     Maximum number of open files for the process is reached.


    See also:    fpDup2 (137  )


                Listing:  ./bunixex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  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 b a s e u n i x;


                 v a r  f  :   t e x t;


                 b e g i n
                    i f    f p d u p ( o u t p u t, f)<>0     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 nt o   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 t o  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___.____________________________________________________________________________________________________________*
 *___________

                1.4.10         FpDup2

    Synopsis:    Duplicate one filehandle to another

Declaration:     function  FpDup2(fildes:  cint;fildes2:  cint)  :  cint
                function  FpDup2(var  oldfile:  text;var  newfile:  text)  :  cint
                function  FpDup2(var  oldfile:  File;var  newfile:  File)  :  cint

    Visibility:   default



                                                                                 137

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     Makes fildes2 or NewFile an exact copy of  fildes or OldFile, after having flushed the
                buffer of  OldFile in the case of text or untyped files.

                After a call to fdup2, the 2 file descriptors point to the same physical device (a file, socket,
                or a terminal).

                NewFile can be an assigned file.  If  newfile or fildes was open, it is closed first.  Due to
                the buffering mechanism of Pascal, this has not the same functionality as the dup2 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 zero if succesful, a nonzero return value means the call failed.

       Errors:   In case of error, the following error codes can be reported:


                sys__ebadf    OldFile (or fildes) hasn't been assigned.

                sys__emfile    Maximum number of open files for the process is reached.


    See also:    fpDup (137  )


                Listing:__./bunixex/ex32.pp________________________________________________________________________________________*
 *___________

                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  FpDup2      f u n c t i o n.  }


                 u s e s B a s e U n i 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  t o  1 0  do    w r i t e l n( F , 'L i n e  :   ' ,i ) ;
                    i f  f p d u p 2 ( o u t p u t, f)=-1     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 nt o   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 t o  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     t o  c h e c k  f l u s h i n g.}
                    f p U n l i n k ( 't e x t. t x t' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.11         FpExecv

    Synopsis:    Execute process

Declaration:     function  FpExecv(path:  pChar;argv:  ppChar)  :  cint
                function  FpExecv(path:  AnsiString;argv:  ppchar)  :  cint

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  It gives the
                program the options in argvp.  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.



                                                                                 138

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
       Errors:   Errors are reported in fpErrno (94 ):


                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 \textit{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:    fpExecve (139  ), fpFork (142  )


                Listing:  ./bunixex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v  f u n c t i o n. }


                Uses     Unix    ,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    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}
                    f p E x e c v ( '/ b i n/ l s ' ,pp  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.12         FpExecve

    Synopsis:    Execute process using environment

Declaration:     function  FpExecve(path:  pChar;argv:  ppChar;envp:  ppChar)  :  cint
                function  FpExecve(path:  AnsiString;argv:  ppchar;envp:  ppchar)  :  cint

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  It gives the
                program the options in argv, and the environment in envp.  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:   Extended error information can be retrieved with fpGetErrno (145  ), and includes the fol-
                lowing:

                                                                                 139

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                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 \textit{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:    fpExecv (138  ), fpFork (142  )


                Listing:  ./bunixex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   Program       t o  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     B a s e U n i x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    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  }
                    f p E x e c V e ( '/ b i n/ l s ', pp  ,e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.13         FpExit

    Synopsis:    Exit the current process

Declaration:     procedure  FpExit(Status:  cint)

    Visibility:   default

Description:     FpExit exits the currently running process, and report Status as the exit status.

 Remark:         If this call is executed,  the normal unit finalization code will not be executed.  This may
                lead to unexpected errors and stray files on your system.  It is therefore recommended to use
                the Halt call instead.

       Errors:   None.

    See also:    FpFork (142  ), FpExecve (139  )


                                                                                 140

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.14         FpFcntl

    Synopsis:    File control operations.

Declaration:     function  FpFcntl(fildes:  cint;cmd:  cint)  :  cint
                function  FpFcntl(fildes:  cint;cmd:  cint;arg:  cint)  :  cint
                function  FpFcntl(fildes:  cint;cmd:  cint;var  arg:  FLock)  :  cint

    Visibility:   default

Description:     Read/set a file's attributes.  Fildes 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.

                F__GetFl     Read the descriptor's flags.

                F__GetOwn        Get the Process ID of the owner of a socket.

                F__SetFd     Set the close_on_exec flag of  fildes.  (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 the 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.

                The function returns 0 if successful, -1 otherwise.

       Errors:   On error, -1 is returned.  Use fpGetErrno (145  ) for extended error information.

                sys__ebadf     Fd has a bad file descriptor.

                sys__eagain or sys__eaccess            For \textbf{F_SetLk}, if the lock is held by another process.
                1.4.15         fpfdfillset

    Synopsis:    Set all filedescriptors in the set.

Declaration:     function  fpfdfillset(var  nset:  TFDSet)  :  cint

    Visibility:   default

Description:     fpfdfillset sets all filedescriptors in nset.

    See also:    FpSelect (165  ), FpFD_ZERO (142  ), FpFD_IsSet (142  ), FpFD_Clr (141  ), FpFD_Set (142  )
                1.4.16         fpFD__CLR

    Synopsis:    Clears a filedescriptor in a set

Declaration:     function  fpFD_CLR(fdno:  cint;var  nset:  TFDSet)  :  cint

    Visibility:   default

Description:     FpFD_Clr clears file descriptor fdno in filedescriptor set nset.

                For an example, see FpSelect (165  ).

       Errors:   None.

    See also:    FpSelect (165  ), FpFD_ZERO (142  ), FpFD_Set (142  ), FpFD_IsSet (142  )



                                                                                 141

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.17         fpFD__ISSET

    Synopsis:    Check whether a filedescriptor is set

Declaration:     function  fpFD_ISSET(fdno:  cint;const  nset:  TFDSet)  :  cint

    Visibility:   default

Description:     FpFD_Set Checks whether file descriptor fdNo in filedescriptor set fds is set.  It returns zero
                if the descriptor is not set, 1 if it is set.  If the number of the filedescriptor it wrong, -1 is
                returned.

                For an example, see FpSelect (165  ).

       Errors:   If an invald file descriptor number is passed, -1 is returned.

    See also:    FpSelect (165  ), FpFD_ZERO (142  ), FpFD_Clr (141  ), FpFD_Set (142  )
                1.4.18         fpFD__SET

    Synopsis:    Set a filedescriptor in a set

Declaration:     function  fpFD_SET(fdno:  cint;var  nset:  TFDSet)  :  cint

    Visibility:   default

Description:     FpFD_Set sets file descriptor fdno in filedescriptor set nset.

                For an example, see FpSelect (165  ).

       Errors:   None.

    See also:    FpSelect (165  ), FpFD_ZERO (142  ), FpFD_Clr (141  ), FpFD_IsSet (142  )
                1.4.19         fpFD__ZERO

    Synopsis:    Clear all file descriptors in set

Declaration:     function  fpFD_ZERO(var  nset:  TFDSet)  :  cint

    Visibility:   default

Description:     FpFD_ZERO clears all the filedescriptors in the file descriptor set nset.

                For an example, see FpSelect (165  ).

       Errors:   None.

    See also:    FpSelect (165  ), FpFD_Clr (141  ), FpFD_Set (142  ), FpFD_IsSet (142  )
                1.4.20         FpFork

    Synopsis:    Create child process

Declaration:     function  FpFork  :  TPid

    Visibility:   default

Description:     FpFork creates a child process which is a copy of the parent process.  FpFork returns the
                process ID in the parent process, and zero in the child's process.  (you can get the parent's
                PID with fpGetPPid (148  )).



                                                                                 142

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
       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:    fpExecve (139  ), #rtl.linux.Clone (670  )
                1.4.21         FPFStat

    Synopsis:    Retrieve file information about a file descriptor.

Declaration:     function  FpFStat(fd:  cint;var  sb:  Stat)  :  cint
                function  FPFStat(var  F:  Text;var  Info:  Stat)  :  Boolean
                function  FPFStat(var  F:  File;var  Info:  Stat)  :  Boolean

    Visibility:   default

Description:     FpFStat gets information about the file specified in one of the following:


                Fd   a valid file descriptor.

                F  an opened text file or untyped file.


                and stores it in Info, which is of type stat (126  ).  The function returns zero if the call was
                succesfull, a nonzero return value indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                sys__enoent      Path does not exist.


    See also:    FpStat (173  ), FpLStat (152  )


                Listing:  ./bunixex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 8;


                {   Program       t o  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 B a s e U n i 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  t o  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  f p s t a t (  't e s t. f i l' , i n f o)<>0    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 :   ' ,f p g e t e r r n o) ;
                             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 o.s t _i n o ) ;
                    w r i t e l n ( 'Mode           :  ' , i n f o.s t _m o d e ) ;



                                                                                 143

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                    w r i t e l n ( ' n l i n k     :  ' , i n f o.s t _n l i n k) ;
                    w r i t e l n ( ' u i d         :  ' , i n f o.s t _u i d ) ;
                    w r i t e l n ( ' g i d         :  ' , i n f o.s t _g i d ) ;
                    w r i t e l n ( ' r d e v       :  ' , i n f o.s t _r d e v ) ;
                    w r i t e l n ( ' S i z e       :  ' , i n f o.s t _s i z e ) ;
                    w r i t e l n ( ' B l k s i z e :  ' , i n f o.s t _b l k s i z e) ;
                    w r i t e l n ( ' B l o c k s   :  ' , i n f o.s t _b l o c k s) ;
                    w r i t e l n ( 'a t i m e      :  ' , i n f o.s t _a t i m e) ;
                    w r i t e l n ( 'mtime          :  ' , i n f o.s t _m t i m e) ;
                    w r i t e l n ( ' c t i m e     :  ' , i n f o.s t _c t i m e) ;
                    {  Remove       f i l e }
                    e r a s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.22         FpFtruncate

    Synopsis:    Truncate file on certain size.

Declaration:     function  FpFtruncate(fd:  cint;flength:  TOff)  :  cint

    Visibility:   default

Description:     FpFTruncate sets the length of a file in fd on flength bytes, where flength must be less
                than or equal to the current length of the file in fd.

                The function returns zero if the call was successful, a nonzero return value indicates that an
                error occurred.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpOpen (157  ), FpClose (136  ), FpRead (161  ), FpWrite (182  ), FpLSeek (151  )
                1.4.23         FpGetcwd

    Synopsis:    Retrieve the current working directory.

Declaration:     function  FpGetcwd(path:  pChar;siz:  TSize)  :  pChar
                function  FpGetcwd  :  AnsiString

    Visibility:   default

Description:     fpgetCWD  returns  the  current  working  directory  of  the  running  process.  It  is  returned  in
                Path, which points to a memory location of at least siz bytes.

                If  the  function  is  succesful,  a  pointer  to  Path  is  returned,  or  a  string  with  the  result.  On
                error Nil or an empty string are returned.

       Errors:   On error Nil or an empty string are returned.

    See also:    FpGetPID (147  ), FpGetUID (148  )
                1.4.24         FpGetegid

    Synopsis:    Return effective group ID

Declaration:     function  FpGetegid  :  TGid

    Visibility:   default



                                                                                 144

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     FpGetegid returns the effective group ID of the currently running process.

       Errors:   None.

    See also:    FpGetGid (146  ),  FpGetUid (148  ),  FpGetEUid (146  ),  FpGetPid (147  ),  FpGetPPid (148  ),
                fpSetUID (168  ), FpSetGid (167  )


                Listing:  ./bunixex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  G e t G i d and    G e t E G i d f u n c t i o n s. }


                Uses     B a s e U n i x;


                 b e g i n
                  w r i t e l n ( ' Group     I d  =   ' ,f p g e t g i d,'   E f f e c t i v eg r o u p  I d =   ' , f p g e t e g*
 * i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.25         FpGetEnv

    Synopsis:    Return value of environment variable.

Declaration:     function  FpGetEnv(name:  pChar)  :  pChar
                function  FpGetEnv(name:  String)  :  pChar

    Visibility:   default

Description:     FPGetEnv  returns  the  value  of  the  environment  variable  in  Name.   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.


                Listing:  ./bunixex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 1;


                {   Program       t o  d e m o n s t r a t et h e  GetEnv      f u n c t i o n.  }


                Uses     B a s e U n i x;


                 b e g i n
                    W r i t e l n ( 'Path     i s   :  ' ,f p G e t e n v('PATH    ' ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.26         fpgeterrno

    Synopsis:    Retrieve extended error information.

Declaration:     function  fpgeterrno  :  LongInt

    Visibility:   default

Description:     fpgeterrno returns extended information on the latest error.  It is set by all functions that
                communicate with the kernel or C library.



                                                                                 145

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
       Errors:   None.

    See also:    fpseterrno (167  )
                1.4.27         FpGeteuid

    Synopsis:    Return effective user ID

Declaration:     function  FpGeteuid  :  TUid

    Visibility:   default

Description:     FpGeteuid returns the effective user ID of the currently running process.

       Errors:   None.

    See also:    FpGetUid (148  ),  FpGetGid (146  ),  FpGetEGid (144  ),  FpGetPid (147  ),  FpGetPPid (148  ),
                fpSetUID (168  ), FpSetGid (167  )


                Listing:  ./bunixex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  G e t U i d and    GetEUid       f u n c t i o n s. }


                Uses     B a s e U n i x;


                 b e g i n
                    w r i t e l n ( 'U s e r  I d  =   ' ,f p g e t u i d,'   E f f e c t i v eu s e r  I d =    ', f p g e t e u i*
 * d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.28         FpGetgid

    Synopsis:    Return real group ID

Declaration:     function  FpGetgid  :  TGid

    Visibility:   default

Description:     FpGetgid returns the real group ID of the currently running process.

       Errors:   None.

    See also:    FpGetEGid (144  ), FpGetUid (148  ), FpGetEUid (146  ), FpGetPid (147  ), FpGetPPid (148  ),
                fpSetUID (168  ), FpSetGid (167  )


                Listing:  ./bunixex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  G e t G i d and    G e t E G i d f u n c t i o n s. }


                Uses     B a s e U n i x;


                 b e g i n
                  w r i t e l n ( ' Group     I d  =   ' ,f p g e t g i d,'   E f f e c t i v eg r o u p  I d =   ' , f p g e t e g*
 * i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                 146

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.29         FpGetgroups

    Synopsis:    Get the list of supplementary groups.

Declaration:     function  FpGetgroups(gidsetsize:  cint;var  grouplist:  TGrpArr)  :  cint

    Visibility:   default

Description:     FpGetgroups returns up to gidsetsize groups in GroupList

                If the function is successful, then number of groups that were stored is returned.  On error,
                -1 is returned.

       Errors:   On  error,  -1  is  returned.   Extended  error  information  can  be  retrieved  with  fpGetErrNo
                (145  )

    See also:    FpGetpgrp (147  ), FpGetGID (146  ), FpGetEGID (144  )
                1.4.30         FpGetpgrp

    Synopsis:    Get process group ID

Declaration:     function  FpGetpgrp  :  TPid

    Visibility:   default

Description:     FpGetpgrp returns the process group ID of the current process.

       Errors:   None.

    See also:    fpGetPID (147  ), fpGetPPID (148  ), FpGetGID (146  ), FpGetUID (148  )
                1.4.31         FpGetpid

    Synopsis:    Return current process ID

Declaration:     function  FpGetpid  :  TPid

    Visibility:   default

Description:     FpGetpid returns the process ID of the currently running process.

                Note:  There exist a portable alterative to fpGetpid:  system.GetProcessID. Please use fpGet-
                pid only if you are writing Unix specific code.  System.GetProcessID will work on all operating
                systems.

       Errors:   None.

    See also:    FpGetPPid (148  )


                Listing:__./bunixex/ex16.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  G e t P i d,  G e t P P i d f u n c t i o n. }


                Uses     B a s e U n i x;


                 b e g i n
                    W r i t e l n ( ' P r o c e s sI d  =   ' , f p g e t p i d,'  P a r e n t p r o c e s s I d  =   ' ,f p g e t *
 *p p i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                 147

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.32         FpGetppid

    Synopsis:    Return parent process ID

Declaration:     function  FpGetppid  :  TPid

    Visibility:   default

Description:     FpGetppid returns the Process ID of the parent process.

       Errors:   None.

    See also:    FpGetPid (147  )


                Listing:  ./bunixex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  G e t P i d,  G e t P P i d f u n c t i o n. }


                Uses     B a s e U n i x;


                 b e g i n
                    W r i t e l n ( ' P r o c e s sI d  =   ' , f p g e t p i d,'  P a r e n t p r o c e s s I d  =   ' ,f p g e t *
 *p p i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.33         fpGetPriority

    Synopsis:    Return process priority

Declaration:     function  fpGetPriority(Which:  cint;Who:  cint)  :  cint

    Visibility:   default

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.

                For an example, see FpNice (156  ).

       Errors:   Error information is returned solely by the FpGetErrno (145  ) function:  a priority can be a
                positive or negative value.


                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:    FpSetPriority (167  ), FpNice (156  )
                1.4.34         FpGetuid

    Synopsis:    Return current user ID

Declaration:     function  FpGetuid  :  TUid

    Visibility:   default

Description:     FpGetuid returns the real user ID of the currently running process.
                                                                                 148

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
       Errors:   None.

    See also:    FpGetGid (146  ), FpGetEUid (146  ), FpGetEGid (144  ), FpGetPid (147  ), FpGetPPid (148  ),
                fpSetUID (168  )


                Listing:  ./bunixex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  G e t U i d and    GetEUid       f u n c t i o n s. }


                Uses     B a s e U n i x;


                 b e g i n
                    w r i t e l n ( 'U s e r  I d  =   ' ,f p g e t u i d,'   E f f e c t i v eu s e r  I d =    ', f p g e t e u i*
 * d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.35         FpIOCtl

    Synopsis:    General kernel IOCTL call.

Declaration:     function  FpIOCtl(Handle:  cint;Ndx:  TIOCtlRequest;Data:  Pointer)  :  cint

    Visibility:   default

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:   Extended error information can be retrieved using fpGetErrno (145  ).


                Listing:  ./bunixex/ex54.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 4;


                 u s e s B a s e U n i x,Termio     ;


                {   Program       t o  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 f d e f FreeBSD     }
                        f p I O C t l( 1 ,TIOCGETA     , @ t i o s) ;   //    t h e s e c o n s t a n t s a r e  v e r y OS   d e p*
 * e n d a n t.
                                                                        //    s e e  t h e  t c g e t a t t re x a m p l e f o r  a*
 *  b e t t e r way
                    { $ e n d i f}
                    WriteLn     ( ' I n p u t F l a g s    :  $ ' ,h e x s t r( t 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 t r( t i 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___.____________________________________________________________________________________________________________*
 *___________


                                                                                 149

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.36         FpKill

    Synopsis:    Send a signal to a process

Declaration:     function  FpKill(pid:  TPid;sig:  cint)  :  cint

    Visibility:   default

Description:     fpKill sends 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:   Extended error information can be retrieved using fpGetErrno (145  ):


                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:    FpSigAction (169  ), FpSignal (171  )
                1.4.37         FpLink

    Synopsis:    Create a hard link to a file

Declaration:     function  FpLink(existing:  pChar;newone:  pChar)  :  cint
                function  FpLink(existing:  AnsiString;newone:  AnsiString)  :  cint

    Visibility:   default

Description:     fpLink makes NewOne point to the same file als Existing.  The two files then have the same
                inode  number.  This  is  known  as  a  'hard'  link.  The  function  returns  zero  if  the  call  was
                succesfull, and returns a non-zero value if the call failed.

       Errors:   The following error codes are returned:


                sys__exdev     Existing and NewOne are not on the same filesystem.

                sys__eperm      The filesystem containing Existing and NewOne doesn't support linking files.

                sys__eaccess     Write  access  for  the  directory  containing  NewOne  is  disallowed,  or  one  of  the
                       directories in Existing or NewOne has no search (=execute) permission.

                sys__enoent      A  directory  entry  in  Existing  or  NewOne  does  not  exist  or  is  a  symbolic  link
                       pointing to a non-existent directory.

                sys__enotdir      A directory entry in Existing or NewOne is nor a directory.

                sys__enomem        Insufficient kernel memory.

                sys__erofs    The files are on a read-only filesystem.

                sys__eexist    NewOne already exists.

                sys__emlink      Existing has reached maximal link count.

                sys__eloop     existing or NewOne has a reference to a circular symbolic link,  i.e.  a symbolic
                       link, whose expansion points to itself.

                sys__enospc      The device containing NewOne has no room for another entry.

                sys__eperm      Existing points to .  or ..  of a directory.
                                                                                 150

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
    See also:    fpSymLink (174  ), fpUnLink (179  )


                Listing:  ./bunixex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 1;


                {   Program       t o  d e m o n s t r a t et h e  L i n k  and    U n L i n k f u n c t i o n s. }


                Uses     B a s e U n i x;


                Var    F   :  T e x t ;
                       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 t o  t e s t. t 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  f p L i n k (  't e s t. t x t' , 'new   .t x t ')<>0     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 snew   . t x t }
                    I f  f p U n l i n k ( ' t e s t.t x t ')<>0     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 ') ;
                    R e s e t ( 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    F P U n l i n k ( 'new   . t x t')<>0     then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.38         FpLseek

    Synopsis:    Set file pointer position.

Declaration:     function  FpLseek(fd:  cint;offset:  TOff;whence:  cint)  :  TOff

    Visibility:   default

Description:     FpLSeek sets the current fileposition of file fd to Offset, starting from Whence, which can
                be one of the following:


                Seek__Set     Offset is the absolute position in the file.

                Seek__Cur      Offset is relative to the current position.

                Seek__end     Offset is relative to the end of the file.


                The function returns the new fileposition, or -1 of an error occurred.

                For an example, see FpOpen (157  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpOpen (157  ), FpWrite (182  ), FpClose (136  ), FpRead (161  ), FpFTruncate (144  )



                                                                                 151

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.39         fpLstat

    Synopsis:    Return information about symbolic link.  Do not follow the link

Declaration:     function  fpLstat(path:  pchar;Info:  PStat)  :  cint
                function  fpLstat(Filename:  ansistring;Info:  PStat)  :  cint

    Visibility:   default

Description:     FpLstat  gets  information  about  the  link  specified  in  Path  (or  FileName,  and  stores  it
                in  Info,  which  points  to  a  record  of  type  TStat.   Contrary  to  FpFstat  (143  ),  it  stores
                information about the link, not about the file the link points to.  The function returns zero
                if the call was succesful, a nonzero return value indicates failure.  failed.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function.


                sys__enoent      Path does not exist.


    See also:    FpFStat (143  ), #rtl.unix.StatFS (1581   )


                Listing:  ./unixex/ex29.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 9;


                {   Program       t o  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 B a s e U n i x,U n i 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  t o  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  f p s t a t (  't e s t. f i l' , i n f o)<>0    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  :   ', f p g e t e r r n)o;
                         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  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 o.s t _i n o ) ;
                    w r i t e l n ( 'Mode           :  ' , i n f o.s t _m o d e ) ;
                    w r i t e l n ( ' n l i n k     :  ' , i n f o.s t _n l i n k) ;
                    w r i t e l n ( ' u i d         :  ' , i n f o.s t _u i d ) ;
                    w r i t e l n ( ' g i d         :  ' , i n f o.s t _g i d ) ;
                    w r i t e l n ( ' r d e v       :  ' , i n f o.s t _r d e v ) ;
                    w r i t e l n ( ' S i z e       :  ' , i n f o.s t _s i z e ) ;
                    w r i t e l n ( ' B l k s i z e :  ' , i n f o.s t _b l k s i z e) ;
                    w r i t e l n ( ' B l o c k s   :  ' , i n f o.s t _b l o c k s) ;
                    w r i t e l n ( 'a t i m e      :  ' , i n f o.s t _a t i m e) ;
                    w r i t e l n ( 'mtime          :  ' , i n f o.s t _m t i m e) ;
                    w r i t e l n ( ' c t i m e     :  ' , i n f o.s t _c t i m e) ;


                    I f    f p S y m L i n k(  't e s t. f i l' , 't e s t. l n k' )<>0    then



                                                                                 152

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                        w r i t e l n(  'L i n k  f a i l e d !  E r r n o  : ' ,f p g e t e r r n o) ;


                    i f    f p l s t a t ( ' t e s t.l n k ', @ i n f o)<>0    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  :   ', f p g e t e r r n)o;
                         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 o.s t _i n o ) ;
                    w r i t e l n ( 'Mode           :  ' , i n f o.s t _m o d e ) ;
                    w r i t e l n ( ' n l i n k     :  ' , i n f o.s t _n l i n k) ;
                    w r i t e l n ( ' u i d         :  ' , i n f o.s t _u i d ) ;
                    w r i t e l n ( ' g i d         :  ' , i n f o.s t _g i d ) ;
                    w r i t e l n ( ' r d e v       :  ' , i n f o.s t _r d e v ) ;
                    w r i t e l n ( ' S i z e       :  ' , i n f o.s t _s i z e ) ;
                    w r i t e l n ( ' B l k s i z e :  ' , i n f o.s t _b l k s i z e) ;
                    w r i t e l n ( ' B l o c k s   :  ' , i n f o.s t _b l o c k s) ;
                    w r i t e l n ( 'a t i m e      :  ' , i n f o.s t _a t i m e) ;
                    w r i t e l n ( 'mtime          :  ' , i n f o.s t _m t i m e) ;
                    w r i t e l n ( ' c t i m e     :  ' , i n f o.s t _c t i m e) ;
                    {  Remove       f i l e and     l i n k }
                    e r a s e ( f ) ;
                    f p u n l i n k ( 't e s t. l n k' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.40         FpMkdir

    Synopsis:    Create a new directory

Declaration:     function  FpMkdir(path:  pChar;Mode:  TMode)  :  cint
                function  FpMkdir(path:  AnsiString;Mode:  TMode)  :  cint

    Visibility:   default

Description:     FpMkDir creates a new directory Path, and sets the new directory's mode to Mode.  Path can
                be an absolute path or a relative path.  Note that only the last element of the directory will
                be created, higher level directories must already exist, and must be writeable by the current
                user.

                On succes, 0 is returned.  if the function fails, -1 is returned.

                Note:  There exist a portable alterative to fpMkDir:  system.mkdir.  Please use fpMkDir only
                if you are writing Unix specific code.  System.mkdir will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    fpGetCWD (144  ), fpChDir (133  )
                1.4.41         FpMkfifo

    Synopsis:    Create FIFO (named pipe) in file system

Declaration:     function  FpMkfifo(path:  pChar;Mode:  TMode)  :  cint
                function  FpMkfifo(path:  AnsiString;Mode:  TMode)  :  cint

    Visibility:   default

                                                                                 153

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     fpMkFifo creates named a named pipe in the filesystem, with name Path and mode Mode.

                The function returns zero if the command was succesful, and nonzero if it failed.

       Errors:   The error codes include:


                sys__emfile    Too many file descriptors for this process.

                sys__enfile   The system file table is full.
                1.4.42         Fpmmap

    Synopsis:    Create memory map of a file

Declaration:     function  Fpmmap(start:  pointer;len:  size_t;prot:  cint;flags:  cint;
                                         fd:  cint;offst:  off_t)  :  pointer

    Visibility:   default

Description:     FpMMap maps or unmaps files or devices into memory.  The different arguments determine
                what and how the file is mapped:


                adr  Address where to mmap the device.  This address is a hint, and may not be followed.

                len  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.

                       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.

                off 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  extended  error  information  is  returned  by  the  FpGetErrno
                (145  ) function.


                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 writing.

                Sys__EAGAIN           fd is locked, or too much memory is locked.



                                                                                 154

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                Sys__ENOMEM            Not enough memory for this operation.


    See also:    FpMUnMap (155  )


                Listing:  ./unixex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   Program       t o  d e m o n s t r a t et h e  MMap     f u n c t i o n. }


                Uses     B a s e U n i x,U n i x;


                Var    S         :  S t r i n g;
                        f d      :  c i n t;
                       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  t h e  s t r i n g';
                    Len  :=  Length    ( S ) ;
                    f d:=  fpOpen    (  't e s t f i l e.t x t' ,O _wrOnly       o r  o _c r e a t ) ;
                    I f  f d=-1     then
                       H a l t ( 1 ) ;
                    I f  f p W r i t e(f d ,S [ 1 ] ,Len  )=-1     then
                       H a l t ( 2 ) ;
                    f p C l o s e(f d ) ;
                    f d:=  fpOpen    (  't e s t f i l e.t x t' ,O _r d O n l y ) ;
                    i f  f d=-1     then
                       H a l t ( 3 ) ;
                    P := P c h a r( fpmmap    ( n i l, l e n+1  ,  PROT_READ         o r PROT_WRITE        , MAP_PRIVATE        , f*
 * d , 0 ) ) ;


                    I f  l o n g i n t(P )=-1     then
                       H a l t ( 4 ) ;
                    W r i t e l n(' Read     i n memory         : ',P  ) ;
                    f p c l o s e(f d ) ;
                    i f  fpMUnMap      ( P ,Len  )<>0     Then
                       H a l t( f p g e t e r r n o) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.43         Fpmunmap

    Synopsis:    Unmap previously mapped memory block

Declaration:     function  Fpmunmap(start:  pointer;len:  size_t)  :  cint

    Visibility:   default

Description:     FpMUnMap unmaps the memory block of size Len, pointed to by Adr, which was previously
                allocated with FpMMap (154  ).

                The function returns True if successful, False otherwise.

                For an example, see FpMMap (154  ).

       Errors:   In case of error the function returns a nonzero value, extended error information is returned
                by the FpGetErrno (145  ) function.  See FpMMap (154  ) for possible error values.

    See also:    FpMMap (154  )



                                                                                 155

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.44         FpNanoSleep

    Synopsis:    Suspend process for a short time

Declaration:     function  FpNanoSleep(req:  ptimespec;rem:  ptimespec)  :  cint

    Visibility:   default

Description:     FpNanoSleep suspends the process till a time period as specified in req has passed.  Then
                the function returns.  If the call was interrupted (e.g.  by some signal) then the function may
                return earlier, and rem will contain the remaining time till the end of the intended period.
                In this case the return value will be -1, and fpErrNo will be set to EINTR

                If the function returns without error, the return value is zero.

       Errors:   If an error occurred or the call was interrupted, -1 is returned.  Extended error information
                can be retrieved using fpGetErrno (145  ).

    See also:    FpPause (159  ), FpAlarm (133  )


                Listing:  ./bunixex/ex72.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 7 2;


                {   Program       t o  d e m o n s t r a t et h e  N a n o S l e e p f u n c t i o n. }


                 u s e s B a s e U n i x;


                Var
                    Req  , Rem    :  TimeSpec       ;
                    Res    :   L o n g i n t;


                 b e g i n
                    With     Req    do
                        b e g i n
                        t v _s e c: = 1 0 ;
                        t v _n s e c: = 1 0 0 ;
                       end   ;
                    Write    ( 'N a n o S l e e p r e t u r n e d :  ' ) ;
                    F l u s h(Output     ) ;
                    Res  : = ( f p N a n o S l e e(p@Req   ,@rem   ) ) ;
                    W r i t e l n(r e s) ;
                    I f  ( r e s<>0)     then
                       With     rem    do
                           b e g i n
                           W r i t e l n(' R e m a i n i n gs e c o n d s        :   ' ,t v _s e c ) ;
                           W r i t e l n(' R e m a i n i n gn a n o s e c o n d s:   ' ,t v _n s e c) ;
                           end  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.45         fpNice

    Synopsis:    Set process priority

Declaration:     function  fpNice(N:  cint)  :  cint

    Visibility:   default


                                                                                 156

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
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.

                If the function is succesful, zero is returned.  On error, a nonzero value is returned.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function.


                sys__eperm     A non-superuser tried to specify a negative N, i.e.  do a priority increase.


    See also:    FpGetPriority (148  ), FpSetPriority (167  )


                Listing:  ./unixex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   Program       t o  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     B a s e U n i x,U n i 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 yt o  5 ' ) ;
                    f p s e t p r i o r i t y(p r i o _p r o c e s s,f p g e t p i d, 5 ) ;
                    w r i t e l n ( 'New     p r i o r i t y=   ' ,f p g e t p r i o r i t y(p r i o _p r o c e s s,f p g e t p i d*
 *) ) ;
                    w r i t e l n ( 'D o i n g  n i c e 1 0 ' ) ;
                    f p n i c e ( 1 0 ) ;
                    w r i t e l n ( 'New     P r i o r i t y=   ' ,f p g e t p r i o r i t y(p r i o _p r o c e s s,f p g e t p i d*
 *) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.46         FpOpen

    Synopsis:    Open file and return file descriptor

Declaration:     function  FpOpen(path:  pChar;flags:  cint;Mode:  TMode)  :  cint
                function  FpOpen(path:  pChar;flags:  cint)  :  cint
                function  FpOpen(path:  AnsiString;flags:  cint)  :  cint
                function  FpOpen(path:  AnsiString;flags:  cint;Mode:  TMode)  :  cint
                function  FpOpen(path:  String;flags:  cint)  :  cint
                function  FpOpen(path:  String;flags:  cint;Mode:  TMode)  :  cint

    Visibility:   default

Description:     FpOpen opens a file in Path with flags flags and mode Mode One of the following:


                O__RdOnly        File is opened Read-only

                O__WrOnly        File is opened Write-only

                O__RdWr       File is opened Read-Write


                The flags may beOR-ed with one of the following constants:


                O__Creat     File is created if it doesn't exist.

                O__Excl    If the file is opened with O_Creat and it already exists, the call wil fail.

                O__NoCtty       If the file is a terminal device, it will NOT become the process' controlling ter-
                       minal.

                O__Trunc      If the file exists, it will be truncated.



                                                                                 157

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                O__Append       the file is opened in append mode.  Before each write, the file pointer is positioned
                      at the end of the file.

                O__NonBlock        The file is opened in non-blocking mode.  No operation on the file descriptor
                      will cause the calling process to wait till.

                O__NDelay      Idem as O_NonBlock

                O__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.

                O__NoFollow       if the file is a symbolic link, the open fails.  (linux 2.1.126 and higher only)

                O__Directory       if the file is not a directory, the open fails.  (linux 2.1.126 and higher only)


                Path can be of type PChar or String.  The optional mode argument specifies the permissions
                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:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpClose (136  ), FpRead (161  ), FpWrite (182  ), FpFTruncate (144  ), FpLSeek (151  )


                Listing:  ./bunixex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 9;


                {   Program       t o  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     B a s e U n i 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    :  C i n t;


                 b e g i n
                    FD :=  fpOpen      ( ' T e s t.d a t ' ,O _WrOnly       o r  O _C r e a t) ;
                    i f  FD  >0   then
                        b e g i n
                        i f  l e n g t h(L i n e)<>  f p 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 t o  f i l e !  ') ;
                        f p C l o s e(FD ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.47         FpOpendir

    Synopsis:    Open a directory for reading

Declaration:     function  FpOpendir(dirname:  pChar)  :  pDir
                function  FpOpendir(dirname:  AnsiString)  :  pDir
                function  FpOpendir(dirname:  shortString)  :  pDir

    Visibility:   default

Description:     FpOpenDir opens the directory DirName, and returns a pdir pointer to a Dir (118  ) record,
                which can be used to read the directory structure.  If the directory cannot be opened, nil
                is returned.
                                                                                 158

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpCloseDir (136  ), FpReadDir (162  )


                Listing:__./bunixex/ex35.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 3 5;


                {   Program       t o  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     B a s e U n i x;


                Var    T h e D i r  :  P D i r;
                        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;


                 b e g i n
                    T h e D i r:= f p O p e n D i r('. / . ') ;
                    Repeat
                //         E n t r y:= f p T e l l D i r(T h e D i r) ;
                        A D i r e n t:=f p R e a d D i r( T h e D i r^ ) ;
                        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       :  ' , d _f i l e n o) ;
                //                W r i t e l n ( ' O f f s e t    :   ' ,d _o f f ) ;
                               W r i t e l n(  'R e c l e n     :  ' , d _r e c l e n) ;
                               W r i t e l n(  'Name            :  ' , p c h a r(@d _name     [ 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    w o u l d  l i k e t o  s e e  a g a i n ( - 1   t o  s t o p) :  ' )*
 * ;
                       ReadLn       ( E n t r y) ;
                        I f  E n t r y<>-1    then
                           b e g i n
                //             f p S e e k D i r( TheDir    , E n t r y) ;                          / /  n o t  i m p l e m e n t e*
 * df o r  v a r i o u s p l a t f o r m s
                           A D i r e n t:= f p R e a d D i r( T h e D i r^ ) ;
                           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       :   ' ,d _f i l e 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     :   ' ,d _r e c l e n) ;
                                  W r i t e l n ( 'Name            :   ' ,p c h a r(@d _name     [ 0 ] ) ) ;
                                  end  ;
                       end   ;
                    U n t i l  E n t r y=-1;
                    f p C l o s e D i r( T h e D i r^ ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.48         FpPause

    Synopsis:    Wait for a signal to arrive

Declaration:     function  FpPause  :  cint



                                                                                 159

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
    Visibility:  default

Description:     FpPause  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.

                For an example, see fpAlarm (133  ).
                1.4.49         FpPipe

    Synopsis:    Create a set of pipe file handlers

Declaration:     function  FpPipe(var  fildes:  TFilDes)  :  cint

    Visibility:   default

Description:     FpPipe creates a pipe, i.e.  two file objects, one for input, one for output.  The filehandles
                are returned in the array fildes.  The input handle is in the 0-th element of the array, the
                output handle is in the 1-st element.

                The function returns zero if everything went succesfully, a nonzero return value indicates an
                error.

       Errors:   In case the function fails, the following return values are possible:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    #rtl.unix.POpen (1578   ), fpMkFifo (153  )


                Listing:  ./bunixex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n P i p ef u n c t i o n.  }


                Uses     B a s e U n i x,U n i x;


                Var     p i p i,p i p o  :  T e x t ;
                        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 gP i p e s. ') ;
                    I f  a s s i g n p i p e(p i p i,p i p o)<>0     then
                        W r i t e l n('E r r o r  a s s i g n i n gp i p e s  ! ', f p g e t e r r n)o;
                    W r i t e l n ( ' W r i t i n gt o   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 f r o m  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     f r o m 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___.____________________________________________________________________________________________________________*
 *___________


                                                                                 160

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.50         FppRead

    Synopsis:    Positional read:  read from file descriptor at a certain position.

Declaration:     function  FpPRead(fd:  cint;buf:  pChar;nbytes:  TSize;offset:  TOff)
                                            :  TsSize
                function  FppRead(fd:  cint;var  buf;nbytes:  TSize;offset:  TOff)  :  TsSize

    Visibility:   default

Description:     FpPRead reads nbytes bytes from file descriptor fd into buffer buf starting at offset offset.
                Offset is measured from the start of the file.  This function can only be used on files, not
                on pipes or sockets (i.e.  any seekable file descriptor).

                The function returns the number of bytes actually read, or -1 on error.

       Errors:   On error, -1 is returned.

    See also:    FpReadV (164  ), FpPWrite (161  )
                1.4.51         FppWrite

    Synopsis:    Positional write:  write to file descriptor at a certain position.

Declaration:     function  FpPWrite(fd:  cint;buf:  pChar;nbytes:  TSize;offset:  TOff)
                                              :  TsSize
                function  FppWrite(fd:  cint;const  buf;nbytes:  TSize;offset:  TOff)
                                              :  TsSize

    Visibility:   default

Description:     FpPWrite  writes  nbytes  bytes  from  buffer  buf  into  file  descriptor  fd  starting  at  offset
                offset.  Offset is measured from the start of the file.  This function can only be used on
                files, not on pipes or sockets (i.e.  any seekable file descriptor).

                The function returns the number of bytes actually written, or -1 on error.

       Errors:   On error, -1 is returned.

    See also:    FpPRead (161  ), FpWriteV (182  )
                1.4.52         FpRead

    Synopsis:    Read data from file descriptor

Declaration:     function  FpRead(fd:  cint;buf:  pChar;nbytes:  TSize)  :  TsSize
                function  FpRead(fd:  cint;var  buf;nbytes:  TSize)  :  TsSize

    Visibility:   default

Description:     FpdRead reads at most nbytes 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:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpOpen (157  ), FpClose (136  ), FpWrite (182  ), FpFTruncate (144  ), FpLSeek (151  )


                Listing:  ./bunixex/ex20.pp
                                                                                 161

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 0;


                {   Program       t o  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 e f u n c t i o n.s }


                Uses     B a s e U n i x;


                Const      Data     :  s t r i n g[ 1 0 ]  =  ' 1 2 3 4 5 6 7 8 9'0;


                Var    FD    :  c i n t;
                        l  :   l o n g i n t;


                 b e g i n
                    FD :=  fpOpen    (  't e s t. d a t' ,o _w r o n l y  o r  o _c r e a t , & 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  t o  1 0  do
                           i f  f p W r i t e ( 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     w r i t i n g ! ' ) ;
                               h a l t( 1 ) ;
                              end   ;
                        f p C l o s e(FD ) ;
                       FD  := fpOpen     ( ' t e s t.d a t ', o _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  t o  5  do
                               i f  f p 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 ! ') ;
                                  H a l t( 2 ) ;
                                  end  ;
                           f p 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 }
                           {  F o r   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 :=  fpOpen    (  't e s t. d a t' ,o _w r o n l y, & 6 6 6 ) ;
                           i f  FD  >0   then
                              b e g i n
                               i f  f p f T r u n c a t(eFD ,60) < >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 p C l o s e( FD  ) ;
                              end   ;
                           end  ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.53         FpReaddir

    Synopsis:    Read entry from directory

Declaration:     function  FpReaddir(var  dirp:  Dir)  :  pDirent

    Visibility:   default

Description:     FpReadDir reads the next entry in the directory pointed to by dirp.  It returns a pdirent
                pointer to a dirent (119  ) record describing the entry.  If the next entry can't be read, Nil is



                                                                                 162

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                returned.

                For an example, see FpOpenDir (158  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpCloseDir (136  ), FpOpenDir (158  )
                1.4.54         fpReadLink

    Synopsis:    Read destination of symbolic link

Declaration:     function  fpReadLink(name:  pchar;linkname:  pchar;maxlen:  size_t)  :  cint
                function  fpReadLink(Name:  ansistring)  :  ansistring

    Visibility:   default

Description:     FpReadLink  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.
                Extended error information is returned by the FpGetErrno (145  ) function.


                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 translating 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:    FpSymLink (174  )


                Listing:  ./unixex/ex62.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   Program       t o  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     B a s e U n i x,U n i x;


                Var    F   :  T e x t ;
                       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 t o  t e s t. t 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  f p S y m L i n k ( 't e s t. t x t' , 'new   .t x t ')<>0     then



                                                                                 163

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                        w r i t e l n(  'E r r o r when     s y m l i n k i n g! ' ) ;
                    S := f p 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 t o  :   ' ,S ) ;
                  {  Now     r e m o v e l i n k s }
                   I f  f p U n l i n k( ' new  . t x t')<>0     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  f p U n l i n k( ' t e s t. t x t')<>0     then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.55         FpReadV

    Synopsis:    Vector read:  Read into multiple buffers

Declaration:     function  FpReadV(fd:  cint;const  iov:  piovec;iovcnt:  cint)  :  TsSize

    Visibility:   default

Description:     FpReadV reads data from file descriptor fd and writes it into iovcnt buffers described by the
                tiovec (128  ) buffers pointed to by iov.  It works like fpRead (161  ) only on multiple buffers.

       Errors:   On error, -1 is returned.

    See also:    FpWriteV (182  ), FpPWrite (161  ), FpPRead (161  )
                1.4.56         FpRename

    Synopsis:    Rename file

Declaration:     function  FpRename(old:  pChar;newpath:  pChar)  :  cint
                function  FpRename(old:  AnsiString;newpath:  AnsiString)  :  cint

    Visibility:   default

Description:     FpRename renames the file Old to NewPath.  NewPath can be in a different directory than
                Old, but it cannot be on another partition (device).  Any existing file on the new location
                will be replaced.

                If the operation fails, then the Old file will be preserved.

                The function returns zero on succes, a nonzero value indicates failure.

                Note:  There exist a portable alterative to fpRename:  system.rename.  Please use fpRename
                only if you are writing Unix specific code.  System.rename will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                sys__eisdir    NewPath exists and is a directory, but Old is not a directory.

                sys__exdev     NewPath and Old are on different devices.

                sys__enotempty or sys__eexist               NewPath is an existing, non-empty directory.

                sys__ebusy     Old or NewPath is a directory and is in use by another process.

                sys__einval    NewPath is part of  Old.

                sys__emlink      OldPath  or  NewPath  already  have  tha  maximum  amount  of  links  pointing  to
                       them.



                                                                                 164

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                sys__enotdir     part of  Old or NewPath 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 Old or NewPath is too long.

                sys__enoent     a directory component in Old or NewPath didn't exist.

                sys__enomem        not enough kernel memory.

                sys__erofs   NewPath or Old is on a read-only file system.

                sys__eloop    too many symbolic links were encountered trying to expand Old or NewPath

                sys__enospc     the filesystem has no room for the new directory entry.


    See also:    FpUnLink (179  )
                1.4.57         FpRmdir

    Synopsis:    Remove a directory.

Declaration:     function  FpRmdir(path:  pChar)  :  cint
                function  FpRmdir(path:  AnsiString)  :  cint

    Visibility:   default

Description:     FpRmdir removes the directory Path from the system.  The directory must be empty for this
                call to succeed,  and the user must have the necessary permissions in the parent directory.
                Only  the  last  component  of  the  directory  is  removed,  i.e.  higher-lying  directories  are  not
                removed.

                On success, zero is returned.  A nonzero return value indicates failure.

                Note:  There exist a portable alterative to fpRmDir:  system.rmdir.  Please use fpRmDir only
                if you are writing Unix specific code.  System.rmdir will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).
                1.4.58         fpSelect

    Synopsis:    Wait for events on file descriptors

Declaration:     function  FPSelect(N:  cint;readfds:  pFDSet;writefds:  pFDSet;
                                            exceptfds:  pFDSet;TimeOut:  ptimeval)  :  cint
                function  fpSelect(N:  cint;readfds:  pFDSet;writefds:  pFDSet;
                                            exceptfds:  pFDSet;TimeOut:  cint)  :  cint
                function  fpSelect(var  T:  Text;TimeOut:  ptimeval)  :  cint
                function  fpSelect(var  T:  Text;TimeOut:  time_t)  :  cint

    Visibility:   default

Description:     FpSelect 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.
                                                                                 165

            ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_____________________*
 *_______________
            You can use the functions fpFD_ZERO (142  ), fpFD_Clr (141  ), fpFD_Set (142  ) or fpFD_IsSet
            (142  ) to manipulate the individual elements of a set.

            The pointers can be Nil.

            N is the value of the largest file descriptor in one of the sets, + 1.  In other words, it is the
            position of the last bit which is set in the array of bits.

            TimeOut can be used to set a time limit.  If  TimeOut can be two types :


                 1.TimeOut is of type ptimeval 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 cint.  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.

            The variant with the text file will execute the FpSelect call on the file descriptor associated
            with the text file T

   Errors:   On  error,  the  function  returns  -1.   Extended  error  information  can  be  retrieved  using
            fpGetErrno (145  ).


            SYS__EBADF           An invalid descriptor 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:    fpFD_ZERO (142  ), fpFD_Clr (141  ), fpFD_Set (142  ), fpFD_IsSet (142  )


            Listing:  ./bunixex/ex33.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program       E x a m p l e 3 3;


            {   Program       t o  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     B a s e U n i x;


            Var    FDS     :  T f d s e t;


             b e g i n
                f p f d _z e r o(FDS   ) ;
                f p f d _s e t( 0 ,FDS   ) ;
                W r i t e l n ( ' P r e s s t h e < ENTER    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                {  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 }
                f p 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    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                F p f d _z e r o(FDS   ) ;
                F p F d _s e t  ( 0 ,FDS  ) ;
                i f  f p S e l e c t ( 1 ,@FDS   , n i l, n i l, 2 0 0 0 ) > 0 then
                    W r i t e l n(  'Thank     you    ! ' )
                   {   FD _ISSET     ( 0 ,FDS   )  w o u l d be    t r u e h e r e .  }
                                                                             166

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                    e l s e
                        W r i t e l n(  'Too    l a t e  ! ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.59         fpseterrno

    Synopsis:    Set extended error information.

Declaration:     procedure  fpseterrno(err:  LongInt)

    Visibility:   default

Description:     fpseterrno sets the extended information on the latest error.  It is called by all functions
                that communicate with the kernel or C library.

                Unless a direct kernel call is performed, there should never be any need to call this function.

       Errors:

    See also:    fpgeterrno (145  )
                1.4.60         FpSetgid

    Synopsis:    Set the current group ID

Declaration:     function  FpSetgid(gid:  TGid)  :  cint

    Visibility:   default

Description:     fpSetUID sets the group ID of the current process.  This call will only work if it is executed
                as root, or the program is setgid root.

                On success, zero is returned, on error -1 is returned.

       Errors:   Extended error information can be retrieved with fpGetErrNo (145  ).

    See also:    FpSetUid  (168  ),  FpGetGid  (146  ),  FpGetUid  (148  ),  FpGetEUid  (146  ),  FpGetEGid  (144  ),
                FpGetPid (147  ), FpGetPPid (148  )
                1.4.61         fpSetPriority

    Synopsis:    Set process priority

Declaration:     function  fpSetPriority(Which:  cint;Who:  cint;What:  cint)  :  cint

    Visibility:   default

Description:     fpSetPriority  sets  the  priority  with  which  a  process  is  running.   Which  process(es)  is
                determined by the Which and Who variables.  Which can be one of the pre-defined constants:


                Prio__Process       Who is interpreted as process ID

                Prio__PGrp       Who is interpreted as process group ID

                Prio__User      Who is interpreted as user ID


                Prio is a value in the range -20 to 20.

                For an example, see FpNice (156  ).

                The function returns zero on success, -1 on failure



                                                                                 167

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
       Errors:   Extended error information is returned by the FpGetErrno (145  ) function.


                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:    FpGetPriority (148  ), FpNice (156  )
                1.4.62         FpSetsid

    Synopsis:    Create a new session.

Declaration:     function  FpSetsid  :  TPid

    Visibility:   default

Description:     FpSetsid  creates  a  new  session  (process  group).  It  returns  the  new  process  group  id  (as
                returned by FpGetpgrp (147  ).  This call will fail if the current process is already the process
                group leader.

       Errors:   On  error,  -1  is  returned.   Extended  error  information  can  be  retrieved  with  fpGetErrNo
                (145  )
                1.4.63         fpsettimeofday

    Synopsis:    Set kernel time

Declaration:     function  fpsettimeofday(tp:  ptimeval;tzp:  ptimezone)  :  cint

    Visibility:   default

Description:     FpSetTimeOfDay sets the kernel time to the number of seconds since 00:00, January 1 1970,
                GMT specified in the tp 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.

    See also:    #rtl.unix.FPGetTimeOfDay (1572   )
                1.4.64         FpSetuid

    Synopsis:    Set the current user ID

Declaration:     function  FpSetuid(uid:  TUid)  :  cint

    Visibility:   default

Description:     fpSetUID sets the user ID of the current process.  This call will only work if it is executed
                as root, or the program is setuid root.

                On success, zero is returned, on error -1 is returned.

       Errors:   Extended error information can be retrieved with fpGetErrNo (145  ).

    See also:    FpGetGid (146  ), FpGetUid (148  ), FpGetEUid (146  ), FpGetEGid (144  ), FpGetPid (147  ),
                FpGetPPid (148  ), FpSetGid (167  )



                                                                                 168

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.65         FPSigaction

    Synopsis:    Install signal handler

Declaration:     function  FPSigaction(sig:  cint;act:  psigactionrec;oact:  psigactionrec)
                                                   :  cint

    Visibility:   default

Description:     FPSigaction changes the action to take upon receipt of a signal.  Act and Oact are pointers
                to  a  SigActionRec  (125  )  record.   Sig  specifies  the  signal,  and  can  be  any  signal  except
                SIGKILL or SIGSTOP.

                If  Act is non-nil, then the new action for signal Sig is taken from it.  If  OAct 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  sig is SIGCHLD do not receive notification when child processes
                       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:   Extended error information can be retrieved using fpGetErrno (145  ).


                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:    FpSigProcMask (172  ), FpSigPending (172  ), FpSigSuspend (173  ), FpKill (150  )


                Listing:  ./bunixex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 7;


                {   Program       t o  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 f r o m  a n o t h e r t e r m i n a l t o  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  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }


                 u s e s B a s e U n i x;


                Var
                      oa , na   :   P S i g A c t i o n R e;c


                 P r o c e d u r eDoSig    ( s i g  :  c 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 gs i g n a l:  ' , s i g) ;
                end   ;



                                                                                 169

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________


                 b e g i n
                      new  ( na ) ;
                      new  ( oa ) ;
                      na ^ . s a _H a n d l e r:= S i g A c t i o n H a n d l e(r@DoSig   ) ;
                      f i l l c h a r(na ^ .Sa _Mask     , s i z e o f(na ^ . s a _m a s k) , # 0 ) ;
                      na ^ . S a _F l a g s: = 0 ;
                      { $ i f d e f L i n u x}                          //    L i n u x s p e c i f i c
                         na  ^ .S a _R e s t o r e r:= N i l;
                      { $ e n d i f}
                      i f  f p S i g A c t i o(nS i g U s r 1,na  ,oa )<>0     then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , f p g e t e r r n,o' . ') ;
                         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    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.66         FpSigAddSet

    Synopsis:    Set a signal in a signal set.

Declaration:     function  FpSigAddSet(var  nset:  tsigset;signo:  cint)  :  cint

    Visibility:   default

Description:     FpSigAddSet adds signal Signo to the signal set nset.  The function returns 0 on success.

       Errors:   If an invalid signal number is given, -1 is returned.

    See also:    FpSigEmptySet (170  ), FpSigFillSet (171  ), FpSigDelSet (170  ), FpSigIsMember (171  )
                1.4.67         FpSigDelSet

    Synopsis:    Remove a signal from a signal set.

Declaration:     function  FpSigDelSet(var  nset:  tsigset;signo:  cint)  :  cint

    Visibility:   default

Description:     FpSigDelSet removes signal Signo to the signal set nset.  The function returns 0 on success.

       Errors:   If an invalid signal number is given, -1 is returned.

    See also:    FpSigEmptySet (170  ), FpSigFillSet (171  ), FpSigAddSet (170  ), FpSigIsMember (171  )
                1.4.68         FpsigEmptySet

    Synopsis:    Clear all signals from signal set.

Declaration:     function  FpsigEmptySet(var  nset:  tsigset)  :  cint

    Visibility:   default

Description:     FpSigEmptySet clears all signals from the signal set nset.

       Errors:   None.  This function always returns zero.

    See also:    FpSigFillSet (171  ), FpSigAddSet (170  ), FpSigDelSet (170  ), FpSigIsMember (171  )



                                                                                 170

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.69         FpSigFillSet

    Synopsis:    Set all signals in signal set.

Declaration:     function  FpSigFillSet(var  nset:  tsigset)  :  cint

    Visibility:   default

Description:     FpSigFillSet sets all signals in the signal set nset.

       Errors:   None.  This function always returns zero.

    See also:    FpSigEmptySet (170  ), FpSigAddSet (170  ), FpSigDelSet (170  ), FpSigIsMember (171  )
                1.4.70         FpSigIsMember

    Synopsis:    Check whether a signal appears in a signal set.

Declaration:     function  FpSigIsMember(const  nset:  tsigset;signo:  cint)  :  cint

    Visibility:   default

Description:     FpSigIsMember checks whether SigNo appears in the set nset.  If it is a member, then 1 is
                returned.  If not, zero is returned.

       Errors:   If an invalid signal number is given, -1 is returned.

    See also:    FpSigEmptySet (170  ), FpSigFillSet (171  ), FpSigAddSet (170  ), FpSigDelSet (170  )
                1.4.71         FpSignal

    Synopsis:    Install signal handler (deprecated)

Declaration:     function  FpSignal(signum:  LongInt;Handler:  signalhandler)
                                              :  signalhandler

    Visibility:   default

Description:     FPSignal installs a new signal handler (specified by Handler) for signal SigNum.

                This call has a subset of the functionality provided by the FpSigAction (169  ) call.  The return
                value for FpSignal is the old signal handler, or nil on error.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                SIG__ERR        An error occurred.


    See also:    FpSigAction (169  ), FpKill (150  )


                Listing:  ./bunixex/ex58.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 8;


                {   Program       t o  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 f r o m  a n o t h e r t e r m i n a l t o  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  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }



                                                                                 171

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________


                 u s e s B a s e U n i x;


                 P r o c e d u r eDoSig    ( s i g  :  c 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 gs i g n a l:  ' , s i g) ;
                end   ;


                 b e g i n
                      i f  f p S i g n a l(S i g U s r 1,S i g n a l H a n d l e(r@DoSig   ))=   s i g n a l h a n d l e(rSIG _ERR *
 *  )   then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , f p G e t E r r n,o' . ') ;
                         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    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.72         FpSigPending

    Synopsis:    Return set of currently pending signals

Declaration:     function  FpSigPending(var  nset:  tsigset)  :  cint

    Visibility:   default

Description:     fpSigpending  allows  the  examination  of  pending  signals  (which  have  been  raised  while
                blocked.)  The signal mask of pending signals is returned.

       Errors:   None

    See also:    fpSigAction (169  ), fpSigProcMask (172  ), fpSigSuspend (173  ), fpSignal (171  ), fpKill (150  )
                1.4.73         FpSigProcMask

    Synopsis:    Set list of blocked signals

Declaration:     function  FpSigProcMask(how:  cint;nset:  psigset;oset:  psigset)  :  cint
                function  FpSigProcMask(how:  cint;const  nset:  tsigset;var  oset:  tsigset)
                                                      :  cint

    Visibility:   default

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 nset argu-
                       ment.

                SIG__UNBLOCK              The signals in nset are removed from the set of currently blocked signals.

                SIG__SETMASK              The list of blocked signals is set so nset.

                If  oset is non-nil, then the old set is stored in it.

       Errors:   Errno is used to report errors.

                sys__efault    oset or nset point to an adress outside the range of the process.

                sys__eintr    System call was interrupted.

    See also:    fpSigAction (169  ), fpSigPending (172  ), fpSigSuspend (173  ), fpKill (150  )



                                                                                 172

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.74         FpSigSuspend

    Synopsis:    Set signal mask and suspend process till signal is received

Declaration:     function  FpSigSuspend(const  sigmask:  tsigset)  :  cint

    Visibility:   default

Description:     fpSigSuspend temporarily replaces the signal mask for the process with the one given in
                SigMask, and then suspends the process until a signal is received.

       Errors:   None

    See also:    fpSigAction (169  ), fpSigProcMask (172  ), fpSigPending (172  ), fpSignal (171  ), fpKill (150  )
                1.4.75         FpSleep

    Synopsis:    Suspend process for several seconds

Declaration:     function  FpSleep(seconds:  cuint)  :  cuint

    Visibility:   default

Description:     FpSleep suspends the process till a time period as specified in seconds has passed,  then
                the function returns.  If the call was interrupted (e.g.  by some signal) then the function may
                return earlier, and the return value is the remaining time till the end of the intended period.

                If the function returns without error, the return value is zero.

    See also:    fpPause (159  ), fpAlarm (133  ), fpNanoSleep (156  )


                Listing:  ./bunixex/ex73.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 7 3;


                {   Program       t o  d e m o n s t r a t et h e  F p S l e e p f u n c t i o n. }


                 u s e s B a s e U n i x;


                Var
                    Res    :   L o n g i n t;


                 b e g i n
                    Write    ( 'S l e e p  r e t u r n e d :  ' ) ;
                    F l u s h(Output     ) ;
                    Res  : = ( f p S l e e p( 1 0 ) ) ;
                    W r i t e l n(r e s) ;
                    I f  ( r e s<>0)     then
                        W r i t e l n('R e m a i n i n g s e c o n d s        :  ' , r e s) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.76         FpStat

    Synopsis:    Retrieve file information about a file descriptor.

Declaration:     function  FpStat(path:  pChar;var  buf:  Stat)  :  cint
                function  FpStat(path:  AnsiString;var  buf:  Stat)  :  cint
                function  FpStat(path:  String;var  buf:  Stat)  :  cint
                                                                                 173

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
    Visibility:  default

Description:     FpFStat gets information about the file specified in Path, and stores it in Info, which is of
                type stat (126  ).  The function returns zero if the call was succesfull, a nonzero return value
                indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                sys__enoent     Path does not exist.


    See also:    FpStat (173  ), FpLStat (152  )


                Listing:  ./bunixex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 8;


                {   Program       t o  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 B a s e U n i 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  t o  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  f p s t a t (  't e s t. f i l' , i n f o)<>0    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 :   ' ,f p g e t e r r n o) ;
                             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 o.s t _i n o ) ;
                    w r i t e l n ( 'Mode           :  ' , i n f o.s t _m o d e ) ;
                    w r i t e l n ( ' n l i n k     :  ' , i n f o.s t _n l i n k) ;
                    w r i t e l n ( ' u i d         :  ' , i n f o.s t _u i d ) ;
                    w r i t e l n ( ' g i d         :  ' , i n f o.s t _g i d ) ;
                    w r i t e l n ( ' r d e v       :  ' , i n f o.s t _r d e v ) ;
                    w r i t e l n ( ' S i z e       :  ' , i n f o.s t _s i z e ) ;
                    w r i t e l n ( ' B l k s i z e :  ' , i n f o.s t _b l k s i z e) ;
                    w r i t e l n ( ' B l o c k s   :  ' , i n f o.s t _b l o c k s) ;
                    w r i t e l n ( 'a t i m e      :  ' , i n f o.s t _a t i m e) ;
                    w r i t e l n ( 'mtime          :  ' , i n f o.s t _m t i m e) ;
                    w r i t e l n ( ' c t i m e     :  ' , i n f o.s t _c t i m e) ;
                    {  Remove       f i l e }
                    e r a s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.77         fpSymlink

    Synopsis:    Create a symbolic link



                                                                                 174

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Declaration:     function  fpSymlink(oldname:  pchar;newname:  pchar)  :  cint

    Visibility:  default

Description:     SymLink makes NewName point to the file in OldName, which doesn't necessarily exist.  The
                two files DO NOT have the same inode number.  This is known as a 'soft' link.

                The  permissions  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 zero if the call was succesful, a nonzero value if the call failed.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function.


                sys__eperm     The filesystem containing oldpath and newpath does not 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.

                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 another entry.


    See also:    FpLink (150  ), FpUnLink (179  ), FpReadLink (163  )


                Listing:  ./unixex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   Program       t o  d e m o n s t r a t et h e  SymLink       and    U n L i n k f u n c t i o n s. }


                Uses     b a s e u n i x,U n i x;


                Var    F   :  T e x t ;
                       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 t o  t e s t. t 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  f p S y m L i n k ( 't e s t. t x t' , 'new   .t x t ')<>0     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 snew   . t x t
                        P o i n t i n gnow    t o  a   non  - e x i s t e n t f i l e !   }
                    I f  f p U n l i n k ( ' t e s t.t x t ')<>0     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 c l i n k
                        p o i n t s t o  a  non  -  e x i s t e n tf i l e!  }
                    { $ i- }



                                                                                 175

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                    R e s e t ( F ) ;
                    { $ i+ }
                    I f  I O R e s u l t=0  then
                        W r i t e l n(  'T h i s  s h o u l d n''t   h a p p e n') ;
                  {  Now     r e m o v e new  . t x t  a l s o }
                   I f  f p U n l i n k( ' new  . t x t')<>0     then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.78         fpS__ISBLK

    Synopsis:    Is file a block device

Declaration:     function  fpS_ISBLK(m:  TMode)  :  Boolean

    Visibility:   default

Description:     FpS_ISBLK checks the file mode m to see whether the file is a block device file.  If so it returns
                True.

    See also:    FpFStat (143  ), FpS_ISLNK (177  ), FpS_ISREG (177  ), FpS_ISDIR (176  ), FpS_ISCHR (176  ),
                FpS_ISFIFO (176  ), FpS_ISSOCK (178  )
                1.4.79         fpS__ISCHR

    Synopsis:    Is file a character device

Declaration:     function  fpS_ISCHR(m:  TMode)  :  Boolean

    Visibility:   default

Description:     FpS_ISCHR checks the file mode m to see whether the file is a character device file.  If so it
                returns True.

    See also:    FpFStat (143  ), FpS_ISLNK (177  ), FpS_ISREG (177  ), FpS_ISDIR (176  ), FpS_ISBLK (176  ),
                FpS_ISFIFO (176  ), FpS_ISSOCK (178  )
                1.4.80         fpS__ISDIR

    Synopsis:    Is file a directory

Declaration:     function  fpS_ISDIR(m:  TMode)  :  Boolean

    Visibility:   default

Description:     fpS_ISDIR checks the file mode m to see whether the file is a directory.  If so, it returns True

    See also:    FpFStat (143  ), FpS_ISLNK (177  ), FpS_ISREG (177  ), FpS_ISCHR (176  ), FpS_ISBLK (176  ),
                fpS_ISFIFO (176  ), FpS_ISSOCK (178  )
                1.4.81         fpS__ISFIFO

    Synopsis:    Is file a FIFO

Declaration:     function  fpS_ISFIFO(m:  TMode)  :  Boolean

    Visibility:   default



                                                                                 176

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     FpS_ISFIFO checks the file mode m to see whether the file is a fifo (a named pipe).  If so it
                returns True.

    See also:    FpFStat (143  ), FpS_ISLNK (177  ), FpS_ISREG (177  ), FpS_ISCHR (176  ), FpS_ISBLK (176  ),
                FpS_ISDIR (176  ), FpS_ISSOCK (178  )
                1.4.82         fpS__ISLNK

    Synopsis:    Is file a symbolic link

Declaration:     function  fpS_ISLNK(m:  TMode)  :  Boolean

    Visibility:   default

Description:     FpS_ISLNK checks the file mode m to see whether the file is a symbolic link.  If so it returns
                True

    See also:    FpFStat (143  ), FpS_ISFIFO (176  ), FpS_ISREG (177  ), FpS_ISCHR (176  ), FpS_ISBLK (176  ),
                FpS_ISDIR (176  ), FpS_ISSOCK (178  )


                Listing:  ./bunixex/ex53.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 3;


                {   Program       t o  d e m o n s t r a t et h e  S _ISLNK      f u n c t i o n. }


                Uses     B a s e U n i x,U n i x;


                Var     I n f o :   S t a t;


                 b e g i n
                    i f  f p L S t a t ( p a r a m s t r( 1 ) ,@ i n f o)=0  then
                        b e g i n
                        i f  f p S _I S L N K(i n f o. s t _m o d e)   then
                           W r i t e l n ( ' F i l e i s  a   l i n k' ) ;
                        i f  f p S _I S R E G(i n f o. s t _m o d e)   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  f p S _I S D I R(i n f o. s t _m o d e)   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  fpS _ISCHR     ( i n f o. s t _m o d e)   then
                           W r i t e l n ( ' F i l e i s  a   c h a r a c t e rd e v i c e  f i l e') ;
                        i f  f p S _I S B L K(i n f o. s t _m o d e)   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  f p S _I S F I F O(i n f o. s t _m o d e)  then
                           W r i t e l n ( ' F i l e i s  a   named     p i p e  ( FIFO   ) ') ;
                        i f  fpS _ISSOCK      ( i n f o. s t _m o d e)  then
                           W r i t e l n ( ' F i l e i s  a   s o c k e t') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.83         fpS__ISREG

    Synopsis:    Is file a regular file

Declaration:     function  fpS_ISREG(m:  TMode)  :  Boolean

    Visibility:   default



                                                                                 177

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     FpS_ISREG checks the file mode m to see whether the file is a regular file.  If so it returns
                True

    See also:    FpFStat (143  ), FpS_ISFIFO (176  ), FpS_ISLNK (177  ), FpS_ISCHR (176  ), FpS_ISBLK (176  ),
                FpS_ISDIR (176  ), FPS_ISSOCK (178  )
                1.4.84         fpS__ISSOCK

    Synopsis:    Is file a unix socket

Declaration:     function  fpS_ISSOCK(m:  TMode)  :  Boolean

    Visibility:   default

Description:     FpS_ISSOCK checks the file mode m to see whether the file is a socket.  If so it returns True.

    See also:    FpFStat (143  ), FpS_ISFIFO (176  ), FpS_ISLNK (177  ), FpS_ISCHR (176  ), FpS_ISBLK (176  ),
                FpS_ISDIR (176  ), FpS_ISREG (177  )
                1.4.85         fptime

    Synopsis:    Return the current unix time

Declaration:     function  FpTime(var  tloc:  TTime)  :  TTime
                function  fptime  :  time_t

    Visibility:   default

Description:     FpTime 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. The result is also stored in tloc, if it is specified.

       Errors:   On  error,  -1  is  returned.   Extended  error  information  can  be  retrieved  using  fpGetErrno
                (145  ).


                Listing:  ./bunixex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  d e m o n s t r a t et h e  f p t i m e f u n c t i o n.  }


                Uses     b a s e u n i 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 ( f p t i m e) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.86         FpTimes

    Synopsis:    Return execution times for the current process

Declaration:     function  FpTimes(var  buffer:  tms)  :  TClock

    Visibility:   default



                                                                                 178

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     fpTimes stores the execution time of the current process and child processes in buffer.

                The  return  value  (on  linux)  is  the  number  of  clock  ticks  since  boot  time.  On  error,  -1  is
                returned, and extended error information can be retrieved with fpGetErrno (145  ).

    See also:    fpUTime (180  )
                1.4.87         FpUmask

    Synopsis:    Set file creation mask.

Declaration:     function  FpUmask(cmask:  TMode)  :  TMode

    Visibility:   default

Description:     fpUmask changes the file creation mask for the current user to cmask.  The current mask is
                returned.

    See also:    fpChmod (134  )


                Listing:  ./bunixex/ex27.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 7;


                {   Program       t o  d e m o n s t r a t et h e  Umask      f u n c t i o n. }


                Uses     B a s e U n i x;


                 b e g i n
                    W r i t e l n ( 'Old    Umask      was    :   ', fpUmask     ( & 1 1 1 ) ) ;
                    WRiteln       ( 'New    Umask      i s    :   ', & 1 1 1 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                1.4.88         FpUname

    Synopsis:    Return system name.

Declaration:     function  FpUname(var  name:  UtsName)  :  cint

    Visibility:   default

Description:     Uname  gets  the  name  and  configuration  of  the  current  linux  kernel,  and  returns  it  in  the
                name record.

                On success, 0 is returned, on error, -1 is returned.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpUTime (180  )
                1.4.89         FpUnlink

    Synopsis:    Unlink (i.e.  remove) a file.

Declaration:     function  FpUnlink(path:  pChar)  :  cint
                function  FpUnlink(path:  AnsiString)  :  cint

    Visibility:   default



                                                                                 179

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
Description:     FpUnlink decreases the link count on file Path.  Path can be of type AnsiString or PChar.
                If the link count is zero, the file is removed from the disk.

                The function returns zero if the call was succesfull, a nonzero value indicates failure.

                Note:  There exist a portable alterative to erase files:  system.erase.  Please use fpUnlink only
                if you are writing Unix specific code.  System.erase will work on all operating systems.

                For an example, see FpLink (150  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                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 effec-
                      tive 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:    FpLink (150  ), FpSymLink (174  )
                1.4.90         FpUtime

    Synopsis:    Set access and modification times of a file (touch).

Declaration:     function  FpUtime(path:  pChar;times:  pUtimBuf)  :  cint
                function  FpUtime(path:  AnsiString;times:  pUtimBuf)  :  cint

    Visibility:   default

Description:     FpUtime  sets  the  access  and  modification  times  of  the  file  specified  in  Path.   the  times
                record contains 2 fields, actime, and modtime, both of type time_t (commonly a 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.

                The function returns zero on success, a nonzero return value indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).


                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:    FpTime (178  ), FpChown (135  ), FpAccess (132  )


                Listing:  ./bunixex/ex25.pp

                                                                                 180

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   Program       t o  d e m o n s t r a t et h e  UTime      f u n c t i o n. }


                Uses     Dos   ,B a s e U n i x,Unix   , U n i x U t i l;


                Var     u t i m :   u t i m b u f;
                       dow   ,msec    ,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 e s o u r c e}
                    GetTime       ( h o u r,m i n u t e, s e c o n d,msec   ) ;
                    G e t D a t e ( y e a r,month    , day  , dow  ) ;
                    u t i m. 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) ;
                    u t i m. modtime     := u t i m .a c t i m e;
                    i f  F p u t i m e( 'e x 2 5. pp ' , @utim   )<>0     then
                        w r i t e l n(  'C a l l  t o  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 nt i m e s t o  :   ') ;
                       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___.____________________________________________________________________________________________________________*
 *___________

                1.4.91         FpWait

    Synopsis:    Wait for a child to exit.

Declaration:     function  FpWait(var  stat_loc:  cint)  :  TPid

    Visibility:   default

Description:     fpWait suspends the current process and waits for any child to exit or stop due to a signal.
                It reports the exit status of the exited child in stat_loc.

                The return value of the function is the process ID of the child that exited, or -1 on error.

       Errors:   Extended error information can be retrieved using fpgetErrno (145  ).

    See also:    fpFork (142  ), fpExecve (139  ), fpWaitPid (181  )
                1.4.92         FpWaitPid

    Synopsis:    Wait for a process to terminate

Declaration:     function  FpWaitpid(pid:  TPid;stat_loc:  pcint;options:  cint)  :  TPid
                function  FpWaitPid(pid:  TPid;var  Status:  cint;Options:  cint)  :  TPid

    Visibility:   default

Description:     fpWaitPid waits for a child process with process ID Pid to exit.  The value of  Pid can be
                one of the following:


                Pid < -1    Causes fpWaitPid to wait for any child process whose process group ID equals the
                       absolute value of  pid.

                Pid = -1      Causes fpWaitPid to wait for any child process.



                                                                                 181

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                Pid = 0     Causes fpWaitPid to wait for any child process whose process group ID equals the
                      one of the calling process.

                Pid > 0    Causes fpWaitPid to wait for the child whose process ID equals the value of  Pid.


                The Options parameter can be used to specify further how fpWaitPid behaves:


                WNOHANG             Causes fpWaitpid to return immediately if no child hasexited.

                WUNTRACED               Causes fpWaitPid to return also for children which are stopped, but whose
                      status has not yet been reported.

                ____WCLONE        Causes  fpWaitPid  also  to  wait  for  threads  created  by  the  #rtl.linux.Clone
                      (670  ) call.


                The exit status of the process that caused fpWaitPID is reported in stat_loc or Status.

                Upon return, it returns the process id of the process that exited, 0 if no process exited, or
                -1 in case of failure.

                For an example, see fpFork (142  ).

       Errors:   Extended error information can be retrieved using fpgetErrno (145  ).

    See also:    fpFork (142  ), fpExecve (139  ), fpWait (181  )
                1.4.93         FpWrite

    Synopsis:    Write data to file descriptor

Declaration:     function  FpWrite(fd:  cint;buf:  pChar;nbytes:  TSize)  :  TsSize
                function  FpWrite(fd:  cint;const  buf;nbytes:  TSize)  :  TsSize

    Visibility:   default

Description:     FpWrite writes at most nbytes bytes from buf to file descriptor fd.

                The function returns the number of bytes actually written, or -1 if an error occurred.

       Errors:   Extended error information can be retrieved using fpGetErrno (145  ).

    See also:    FpOpen (157  ), FpClose (136  ), FpRead (161  ), FpFTruncate (144  ), FpLSeek (151  )
                1.4.94         FpWriteV

    Synopsis:    Vector write:  Write from multiple buffers to a file descriptor

Declaration:     function  FpWriteV(fd:  cint;const  iov:  piovec;iovcnt:  cint)  :  TsSize

    Visibility:   default

Description:     FpWriteV writes data to file descriptor fd.  The data is taken from iovcnt buffers described
                by the tiovec (128  ) buffers pointed to by iov.  It works like fpWrite (182  ) only from multiple
                buffers.

       Errors:   On error, -1 is returned.

    See also:    FpReadV (164  ), FpPWrite (161  ), FpPRead (161  )

                                                                                 182

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.95         FreeShellArgV

    Synopsis:    Free the result of a CreateShellArgV (131  ) function

Declaration:     procedure  FreeShellArgV(p:  ppchar)

    Visibility:   default

Description:     FreeShellArgV  frees  the  memory  pointed  to  by  P,  which  was  allocated  by  a  call  to  Cre-
                ateShellArgV (131  ).

       Errors:   None.

    See also:    CreateShellArgV (131  )
                1.4.96         wexitStatus

    Synopsis:    Extract the exit status from the fpWaitPID (181  ) result.

Declaration:     function  wexitStatus(Status:  cint)  :  cint

    Visibility:   default

Description:     WEXITSTATUS can be used to extract the exit status from Status, the result of the FpWait-
                PID (181  ) call.

    See also:    FpWaitPID (181  ), WTERMSIG (184  ), WSTOPSIG (184  ), WIFEXITED (183  ), WIFSIG-
                NALED (183  )
                1.4.97         wifexited

    Synopsis:    Check whether the process exited normally

Declaration:     function  wifexited(Status:  cint)  :  Boolean

    Visibility:   default

Description:     WIFEXITED checks Status and returns True if the status indicates that the process termi-
                nated normally, i.e.  was not stopped by a signal.

    See also:    FpWaitPID (181  ), WTERMSIG (184  ), WSTOPSIG (184  ), WIFSIGNALED (183  ), WEX-
                ITSTATUS (183  )
                1.4.98         wifsignaled

    Synopsis:    Check whether the process was exited by a signal.

Declaration:     function  wifsignaled(Status:  cint)  :  Boolean

    Visibility:   default

Description:     WIFSIGNALED returns True if Status indicates that the process exited because it received a
                signal.

    See also:    FpWaitPID (181  ),  WTERMSIG (184  ),  WSTOPSIG (184  ),  WIFEXITED (183  ),  WEXIT-
                STATUS (183  )
                                                                                 183

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________
                1.4.99         wstopsig

    Synopsis:    Return the exit code from the process.

Declaration:     function  wstopsig(Status:  cint)  :  cint

    Visibility:   default

Description:     WSTOPSIG is an alias for WEXITSTATUS (183  ).

    See also:    FpWaitPID (181  ), WTERMSIG (184  ), WIFEXITED (183  ), WIFSIGNALED (183  ), WEX-
                ITSTATUS (183  )
                1.4.100          wtermsig

    Synopsis:    Return the signal that caused a process to exit.

Declaration:     function  wtermsig(Status:  cint)  :  cint

    Visibility:   default

Description:     WTERMSIG extracts from Status the signal number which caused the process to exit.

    See also:    FpWaitPID (181  ), WSTOPSIG (184  ), WIFEXITED (183  ), WIFSIGNALED (183  ), WEX-
                ITSTATUS (183  )


                                                                                 184


Chapter   2


Reference   for   unit   'Classes'
2.1         Used  units
                                     Table 2.1:  Used units by unit 'Classes'


                                                  __Name____________Page____
                                                    rtlconsts         185
                                                    sysutils        1356
                                                    types             185
                                                    typinfo         1512



2.2         Overview


This documentation describes the FPC classes unit.  The Classes unit contains basic classes
for the Free Component Library (FCL):


     o  a TList (301  ) class for maintaining lists of pointers,

     o  TStringList (347  ) for lists of strings,

     o  TCollection (260  ) to manage collections of objects

     o  TStream (333  ) classes to support streaming.


Furthermore  it  introduces  methods  for  object  persistence,  and  classes  that  understand  an
owner-owned relationship, with automatic memory management.
2.3         Constants,  types  and  variables



2.3.1        Constants

BITSHIFT  =  5


Used to calculate the size of a bits array



                                                             185

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
dupAccept  =  Types.dupAccept


Duplicate values can be added to the list.


dupError  =  Types.dupError


If an attempt is made to add a duplicate value to the list, an EStringListError (217  ) exception
is raised.


dupIgnore  =  Types.dupIgnore


Duplicate values will not be be added to the list, but no error will be triggered.


FilerSignature  :  Array[1..4]  of  Char  =  'TPF0'


Constant that is found at the start of a binary stream containing a streamed component.


fmCreate  =  $FFFF


TFileStream.Create (285  ) creates a new file if needed.


fmOpenRead  =  0


TFileStream.Create (285  ) opens a file with read-only access.


fmOpenReadWrite  =  2


TFileStream.Create (285  ) opens a file with read-write access.


fmOpenWrite  =  1


TFileStream.Create (285  ) opens a file with write-only access.


MASK  =  31


Bitmask with all bits on.


MaxBitFlags  =  MaxBitRec  *  32


Maximum number of bits in TBits collection.


MaxBitRec  =  $FFFF  div  (  SizeOf  (  longint  )  )


Maximum number of bit records in TBits.


MaxListSize  =  Maxint  div  16


This constant sets the maximum number of elements in a TList (301  ).


scAlt  =  $8000



                                                                 186

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
Indicates ALT key in a keyboard shortcut.


scCtrl  =  $4000


indicates CTRL key in a keyboard shortcut.


scNone  =  0


Indicates no special key is presed in a keyboard shortcut.


scShift  =  $2000


Indicates Shift key in a keyboard shortcut.


soFromBeginning  =  0


Seek (335  ) starts relative to the stream origin.


soFromCurrent  =  1


Seek (335  ) starts relative to the current position in the stream.


soFromEnd  =  2


Seek (335  ) starts relative to the stream end.


toEOF  =  Char  (  0  )


Value returned by TParser.Token (317  ) when the end of the input stream was reached.


toFloat  =  Char  (  4  )


Value returned by TParser.Token (317  ) when a floating point value was found in the input
stream.


toInteger  =  Char  (  3  )


Value returned by TParser.Token (317  ) when an integer was found in the input stream.


toString  =  Char  (  2  )


Value returned by TParser.Token (317  ) when a string was found in the input stream.


toSymbol  =  Char  (  1  )


Value returned by TParser.Token (317  ) when a symbol was found in the input stream.


toWString  =  Char  (  5  )


Value returned by TParser.Token (317  ) when a widestring was found in the input stream.



                                                                 187

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
2.3.2        Types

HMODULE  =  LongInt


FPC doesn't support modules yet, so this is a dummy type.


HRSRC  =  LongInt


This type is provided for Delphi compatibilty, it is used for resource streams.


PPointerList  =  ^TPointerList


Pointer to an array of pointers.


PStringItem  =  ^TStringItem


Pointer to a TStringItem (197  ) record.


PStringItemList  =  ^TStringItemList


Pointer to a TStringItemList (197  ).


TActiveXRegType  =  (axrComponentOnly,axrIncludeDescendants)
                      Table 2.2:  Enumeration values for type TActiveXRegType


                                   __Value______________________________Explanation________
                                     axrComponentOnly
                                     axrIncludeDescendants
This type is provided for compatibility only, and is currently not used in Free Pascal.


TAlignment  =  (taLeftJustify,taRightJustify,taCenter)
                           Table 2.3:  Enumeration values for type TAlignment


                        __Value__________________Explanation___________________________________________
                          taCenter                Text is displayed centered.
                          taLeftJustify           Text is displayed aligned to the left
                          taRightJustify          Text is displayed aligned to the right.
The TAlignment type is used to specify the alignment of the text in controls that display a
text.


TAncestorNotFoundEvent  =  procedure(Reader:  TReader;
                                                          const  ComponentName:  String;
                                                          ComponentClass:  TPersistentClass;
                                                          var  Component:  TComponent)  of  object



                                                                 188

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
This event occurs when an ancestor component cannot be found.


TBasicActionClass  =  Class  of  TBasicAction


TBasicAction (237  ) class reference.


TBasicActionLinkClass  =  Class  of  TBasicActionLink


TBasicActionLink (241  ) class reference.


TBiDiMode  =  (bdLeftToRight,bdRightToLeft,bdRightToLeftNoAlign,
                     bdRightToLeftReadingOnly)
                           Table 2.4:  Enumeration values for type TBiDiMode


     __Value_____________________________________Explanation_____________________________________________________________
       bdLeftToRight                             Texts read from left to right.
       bdRightToLeft                             Texts read from right to left.
       bdRightToLeftNoAlign                      Texts read from right to left, but not right-aligned
       bdRightToLeftReadingOnly                  Texts read from right to left
TBiDiMode describes bi-directional support for displaying texts.


TBitArray  =  Array[0..MaxBitRec-1]  of  cardinal


Array to store bits.


TCollectionItemClass  =  Class  of  TCollectionItem


TCollectionItemClass is used by the TCollection.ItemClass (264  ) property of TCollection
(260  ) to identify the descendent class of TCollectionItem (265  ) which should be created and
managed.


TCollectionNotification  =  (cnAdded,cnExtracting,cnDeleting)
                   Table 2.5:  Enumeration values for type TCollectionNotification


                      __Value_________________Explanation_______________________________________________
                        cnAdded               An item is added to the collection.
                        cnDeleting            An item is deleted from the collection.
                        cnExtracting          An item is extracted from the collection.
TCollectionNotification is used in the TCollection (260  ) class to send notifications about
changes to the collection.


TComponentClass  =  Class  of  TComponent


The  TComponentClass  type  is  used  when  constructing  TComponent  (268  )  descendent  in-
stances and when registering components.



                                                                 189

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
TComponentName  =  String


Names  of  components  are  of  type  TComponentName.   By  specifying  a  different  type,  the
Object inspector can handle this property differently than a standard string property.


TComponentState=  Set  of  (csLoading,csReading,csWriting,csDestroying,
                                         csDesigning,csAncestor,csUpdating,csFixups,
                                         csFreeNotification,csInline,csDesignInstance)


Indicates the state of the component during the streaming process.


TComponentStyle=  Set  of  (csInheritable,csCheckPropAvail,csSubComponent,
                                         csTransient)


Describes the style of the component.


TCreateComponentEvent  =  procedure(Reader:  TReader;
                                                        ComponentClass:  TComponentClass;
                                                        var  Component:  TComponent)  of  object


Event handler type, occurs when a component instance must be created when a component
is read from a stream.


TDuplicates  =  Types.TDuplicates


Type to describe what to do with duplicate values in a TStringlist (347  ).


TFilerFlag  =  (ffInherited,ffChildPos,ffInline)
                            Table 2.6:  Enumeration values for type TFilerFlag


                 __Value_____________Explanation_____________________________________________________________
                   ffChildPos        The position of the child on it's parent is included.
                   ffInherited       Stored object is an inherited object.
                   ffInline          Used for frames.
The  TFiler  class  uses  this  enumeration  type  to  decide  whether  the  streamed  object  was
streamed as part of an inherited form or not.


TFilerFlags=  Set  of  (ffChildPos,ffInherited,ffInline)


Set of TFilerFlag (190  )


TFindAncestorEvent  =  procedure(Writer:  TWriter;Component:  TComponent;
                                                   const  Name:  String;
                                                   var  Ancestor:  TComponent;
                                                   var  RootAncestor:  TComponent)  of  object


Event that occurs w



                                                                 190

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
TFindComponentClassEvent  =  procedure(Reader:  TReader;
                                                             const  ClassName:  String;
                                                             var  ComponentClass:  TComponentClass)
                                                              of  object


Event handler type, occurs when a component class pointer must be found when reading a
component from a stream.


TFindGlobalComponent  =  function(const  Name:  String)  :  TComponent


TFindGlobalComponent is a callback used to find a component in a global scope.  It is used
when the streaming system needs to find a component which is not part of the component
which is currently being streamed.  It should return the component with name Name, or Nil
if none is found.

The variable FindGlobalComponent (202  ) is a callback of type TFindGlobalComponent.  It
can be set by the IDE when an unknown reference is found, to offer the designer to redirect
the link to a new component.


TFindMethodEvent  =  procedure(Reader:  TReader;const  MethodName:  String;
                                               var  Address:  Pointer;var  Error:  Boolean)
                                                 of  object


If a TReader (319  ) instance needs to locate a method and it doesn't find it in the streamed
form,  then the OnFindMethod (328  ) event handler will be called,  if one is installed.  This
event can be assigned in order to use different locating methods.  If a method is found, then
its address should be returned in Address.  The Error should be set to True if the reader
should raise an exception after the event was handled.  If it is set to False no exception will
be raised, even if no method was found.  On entry, Error will be set to True.


TGetChildProc  =  procedure(Child:  TComponent)  of  object


Callback used when obtaining child components.


TGetStrProc  =  procedure(const  S:  String)  of  object


This event is used as a callback to retrieve string values.  It is used, among other things, to
pass along string properties in property editors.


THandle  =  System.THandle


This type is used as the handle for THandleStream (293  ) stream descendents


THelpContext  =  -MaxLongint..MaxLongint


Range type to specify help contexts.


THelpEvent  =  function(Command:  Word;Data:  LongInt;var  CallHelp:  Boolean)
                                     :  Boolean  of  object


This event is used for display of online help.


THelpType  =  (htKeyword,htContext)



                                                                 191

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___

                           Table 2.7:  Enumeration values for type THelpType


                                __Value______________Explanation______________________________
                                  htContext          Help type:  Context ID help.
                                  htKeyword          Help type:  Keyword help

Enumeration type specifying the kind of help requested.


TIdentMapEntry  =  record
   Value  :  Integer;
   Name  :  String;
end
TIdentMapEntry  is  used  internally  by  the  IdentToInt  (205  )  and  IntToIdent  (206  )  calls  to
store the mapping between the identifiers and the integers they represent.


TIdentToInt  =  function(const  Ident:  String;var  Int:  LongInt)  :  Boolean


TIdentToInt is a callback used to look up identifiers (Ident) and return an integer value cor-
responding to this identifier (Int).  The callback should return True if a value corresponding
to integer Ident was found, False if not.

A callback of type TIdentToInt should be specified when an integer is registered using the
RegisterIntegerConsts (211  ) call.


TInitComponentHandler  =  function(Instance:  TComponent;
                                                      RootAncestor:  TClass)  :  Boolean


TInitComponentHandler is a callback type.  It is used in the InitInheritedComponent (??  )
call  to  initialize  a  component.  Callbacks  of  this  type  are  registered  with  the  RegisterInit-
ComponentHandler (211  ) call.


TIntToIdent  =  function(Int:  LongInt;var  Ident:  String)  :  Boolean


TIdentToInt is a callback used to look up integers (Ident) and return an identifier (Ident)
that can be used to represent this integer value in an IDE. The callback should return True
if a value corresponding to integer Ident was found, False if not.

A callback of type TIntToIdent should be specified when an integer is registered using the
RegisterIntegerConsts (211  ) call.


TLeftRight  =  ..taRightJustify


TLeftRight is a subrange type based on the TAlignment (188  ) enumerated type.  It contains
only the left and right alignment constants.


TListAssignOp  =  (laCopy,laAnd,laOr,laXor,laSrcUnique,laDestUnique)


This type determines what operation TList.Assign (305  ) or TFPList.assign (291  ) performs.


TListCallback  =  Types.TListCallback



                                                                 192

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___

                         Table 2.8:  Enumeration values for type TListAssignOp



__Value_________________Explanation________________________________________________________________________________________________*
 *________
  laAnd                 Remove all elements not first second list
  laCopy                Clear list and copy all strings from second list.
  laDestUnique          Keep all elements that exists only in list2
  laOr                  Add all elements from second (and optional third) list, eliminate duplicates
  laSrcUnique           Just keep all elements that exist only in source list
  laXor                 Remove elements in second lists, Add all elements from second list not in first list

TListCallback  is  the  method  callback  prototype  for  the  function  that  is  passed  to  the
TFPList.ForEachCall (292  ) call.  The data argument will be filled with all the pointers in
the list (one per call) and the arg argument is the Arg argument passed to the ForEachCall
call.


TListNotification  =  (lnAdded,lnExtracted,lnDeleted)
                       Table 2.9:  Enumeration values for type TListNotification


            __Value_______________Explanation______________________________________________________________________
              lnAdded             List change notification:  Element added to the list.
              lnDeleted           List change notification:  Element deleted from the list.
              lnExtracted         List change notification:  Element extracted from the list.
Kind of list notification event.


TListSortCompare  =  function(Item1:  Pointer;Item2:  Pointer)  :  Integer


Callback type for the list sort algorithm.


TListStaticCallback  =  Types.TListStaticCallback


TListCallback is the procedurald callback prototype for the function that is passed to the
TFPList.ForEachCall (292  ) call.  The data argument will be filled with all the pointers in
the list (one per call) and the arg argument is the Arg argument passed to the ForEachCall
call.


TNotifyEvent  =  procedure(Sender:  TObject)  of  object


Most event handlers are implemented as a property of type TNotifyEvent.  When this is set
to a certain method of a class,  when the event occurs,  the method will be called,  and the
class that generated the event will pass itself along as the Sender argument.


TOperation  =  (opInsert,opRemove)


Operation of which a component is notified.


TPersistentClass  =  Class  of  TPersistent



                                                                 193

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___

                          Table 2.10:  Enumeration values for type TOperation


         __Value____________Explanation_______________________________________________________________________________
           opInsert          A new component is being inserted in the child component list.
           opRemove          A component is being removed from the child component list.

TPersistentClass is the class reference type for the TPersistent (318  ) class.


TPoint  =  Types.TPoint


This  record  describes  a  coordinate.   It  is  used  to  handle  the  Top  (268  )  and  Left  (268  )
properties of TComponent (268  ).

X  represents  the  X-Coordinate  of  the  point  described  by  the  record.   Y  represents  the  Y-
Coordinate of the point described by the record.


TPointerList  =  Array[0..MaxListSize-1]  of  Pointer


Type for an Array of pointers.


TPropertyNotFoundEvent  =  procedure(Reader:  TReader;
                                                         Instance:  TPersistent;
                                                         var  PropName:  String;IsPath:  Boolean;
                                                         var  Handled:  Boolean;
                                                         var  Skip:  Boolean)  of  object


TPropertyNotFoundEvent  is  the  prototype  for  the  TReader.OnPropertyNotFound  (328  )
event.  Reader is the sender of the event, Instance is the instance that is being streamed.
PropInfo is a pointer to the RTTI information for the property being read.  Handled should
be set to True if the handler redirected the unknown property succesfully, and Skip should
be set to True if the value should be skipped.  IsPath determines whether the property refers
to a sub-property.


TReadComponentsProc  =  procedure(Component:  TComponent)  of  object


Callback type when reading a component from a stream


TReaderError  =  procedure(Reader:  TReader;const  Message:  String;
                                         var  Handled:  Boolean)  of  object


Event handler type, called when an error occurs during the streaming.


TReaderProc  =  procedure(Reader:  TReader)  of  object


The TReaderProc reader procedure is a callback procedure which will be used by a TPersis-
tent (318  ) descendent to read user properties from a stream during the streaming process.
The Reader argument is the writer object which can be used read properties from the stream.


TReadWriteStringPropertyEvent  =  procedure(Sender:  TObject;
                                                                     const  Instance:  TPersistent;
                                                                     PropInfo:  PPropInfo;
                                                                     var  Content:  String)  of  object



                                                                 194

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
TReadWriteStringPropertyEvent is the prototype for the TReader.OnReadStringProperty
(330  )  event  handler.   Reader  is  the  sender  of  the  event,  Instance  is  the  instance  that  is
being streamed.  PropInfo is a pointer to the RTTI information for the property being read.
Content is the string as it was read from the stream.


TRect  =  Types.TRect


TRect describes a rectangle in space with its upper-left (in (Top,Left>)) and lower-right (in
(Bottom ,Right)) corners.


TReferenceNameEvent  =  procedure(Reader:  TReader;var  Name:  String)
                                                      of  object


Occurs when a named object needs to be looked up.


TSeekOrigin  =  (soBeginning,soCurrent,soEnd)
                          Table 2.11:  Enumeration values for type TSeekOrigin


      _Value________________Explanation___________________________________________________________________________________
        soBeginning         Offset is interpreted relative to the start of the stream.
        soCurrent           Offset is interpreted relative to the current position in the stream.
        soEnd               Offset is interpreted relative to the end of the stream.
Specifies the origin of the TStream.Seek (335  ) method.


TSetMethodPropertyEvent  =  procedure(Reader:  TReader;
                                                           Instance:  TPersistent;
                                                           PropInfo:  PPropInfo;
                                                           const  TheMethodName:  String;
                                                           var  Handled:  Boolean)  of  object


TSetMethodPropertyEvent is the prototype for the TReader.OnSetMethodProperty (329  )
event.  Reader is the sender of the event, Instance is the instance that is being streamed.
PropInfo is a pointer to the RTTI information for the property being read, and TheMethodName
is  the  name  of  the  method  that  the  property  should  be  set  to.  Handled  should  be  set  to
True if the handler set the property succesfully.


TSetNameEvent  =  procedure(Reader:  TReader;Component:  TComponent;
                                          var  Name:  String)  of  object


Occurs when the reader needs to set a component's name.


TShiftState=  Set  of  (ssShift,ssAlt,ssCtrl,ssLeft,ssRight,ssMiddle,
                                  ssDouble,ssMeta,ssSuper,ssHyper,ssAltGr,ssCaps,
                                  ssNum,ssScroll,ssTriple,ssQuad,ssExtra1,ssExtra2)


This type is used when describing a shortcut key or when describing what special keys are
pressed on a keyboard when a key event is generated.

The set contains the special keys that can be used in combination with a 'normal' key.



                                                                 195

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___

                      Table 2.12:  Enumeration values for type TShiftStateEnum


                                 _Value___________Explanation__________________________________
                                   ssAlt           Alt key pressed
                                   ssAltGr         Alt-GR key pressed.
                                   ssCaps          Caps lock key pressed
                                   ssCtrl          Ctrl key pressed
                                   ssDouble        Double mouse click.
                                   ssExtra1        Extra key 1
                                   ssExtra2        Extra key 2
                                   ssHyper         Hyper key pressed.
                                   ssLeft          Left mouse button pressed.
                                   ssMeta          Meta key pressed.
                                   ssMiddle        Middle mouse button pressed.
                                   ssNum           Num lock key pressed
                                   ssQuad          Quadruple mouse click
                                   ssRight         Right mouse button pressed.
                                   ssScroll        Scroll lock key pressed
                                   ssShift         Shift key pressed
                                   ssSuper         Super key pressed.
                                   ssTriple        Triple mouse click
TShiftStateEnum  =  (ssShift,ssAlt,ssCtrl,ssLeft,ssRight,ssMiddle,
                               ssDouble,ssMeta,ssSuper,ssHyper,ssAltGr,ssCaps,ssNum,
                               ssScroll,ssTriple,ssQuad,ssExtra1,ssExtra2)


Keyboard/Mouse shift state enumerator


TShortCut  =    (  Word  )..High  (  Word  )


Enumeration type to identify shortcut key combinations.


TSmallPoint  =  record
   x  :  SmallInt;
   y  :  SmallInt;
end
Same  as  TPoint  (194  ),  only  the  X  and  Y  ranges  are  limited  to  2-byte  integers  instead  of
4-byte integers.


TStreamOwnership  =  (soReference,soOwned)
                     Table 2.13:  Enumeration values for type TStreamOwnership


          __Value_______________Explanation_________________________________________________________________________
            soOwned             Stream is owned:  it will be freed when the adapter is freed.
            soReference         Stream is referenced only, it is not freed by the adapter



The  ownership  of  a  streamadapter  determines  what  happens  with  the  stream  on  which  a
TStreamAdapter (342  ) acts, when the adapter is freed.



                                                                 196

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
TStreamProc  =  procedure(Stream:  TStream)  of  object


Procedure type used in streaming.


TStringItem  =  record
   FString  :  String;
   FObject  :  TObject;
end
The TStringItem is used to store the string and object items in a TStringList (347  ) string
list instance.  It should never be used directly.


TStringItemList  =  Array[0..MaxListSize]  of  TStringItem


This declaration is provided for Delphi compatibility, it is not used in Free Pascal.


TStringListSortCompare  =  function(List:  TStringList;Index1:  Integer;
                                                        Index2:  Integer)  :  Integer


Callback type used in stringlist compares.


TSynchronizeProcVar  =  procedure


Synchronize callback type


TThreadMethod  =  procedure  of  object


Procedure variable used when synchronizing threads.


TThreadPriority  =  (tpIdle,tpLowest,tpLower,tpNormal,tpHigher,tpHighest,
                               tpTimeCritical)
                       Table 2.14:  Enumeration values for type TThreadPriority


                __Value___________________Explanation_________________________________________________________
                  tpHigher                Thread runs at high priority
                  tpHighest               Thread runs at highest possible priority.
                  tpIdle                  Thread only runs when other processes are idle.
                  tpLower                 Thread runs at a lower priority.
                  tpLowest                Thread runs at the lowest priority.
                  tpNormal                Thread runs at normal process priority.
                  tpTimeCritical          Thread runs at realtime priority.
Enumeration specifying the priority at which a thread runs.


TValueType  =  (vaNull,vaList,vaInt8,vaInt16,vaInt32,vaExtended,vaString,
                       vaIdent,vaFalse,vaTrue,vaBinary,vaSet,vaLString,vaNil,
                       vaCollection,vaSingle,vaCurrency,vaDate,vaWString,vaInt64,
                       vaUTF8String)



                                                                 197

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___

                          Table 2.15:  Enumeration values for type TValueType


                         __Value__________________Explanation_________________________________________
                           vaBinary                Binary data follows.
                           vaCollection            Collection follows
                           vaCurrency              Currency value follows
                           vaDate                  Date value follows
                           vaExtended              Extended value.
                           vaFalse                 Boolean False value.
                           vaIdent                 Identifier.
                           vaInt16                 Integer value, 16 bits long.
                           vaInt32                 Integer value, 32 bits long.
                           vaInt64                 Integer value, 64 bits long.
                           vaInt8                  Integer value, 8 bits long.
                           vaList                  Identifies the start of a list of values
                           vaLString               Ansistring data follows.
                           vaNil                   Nil pointer.
                           vaNull                  Empty value.  Ends a list.
                           vaSet                   Set data follows.
                           vaSingle                Single type follows.
                           vaString                String value.
                           vaTrue                  Boolean True value.
                           vaUTF8String            UTF8 encoded unicode string.
                           vaWString               Widestring value follows.

Enumerated type used to identify the kind of streamed property


TWriteMethodPropertyEvent  =  procedure(Writer:  TWriter;
                                                              Instance:  TPersistent;
                                                              PropInfo:  PPropInfo;
                                                              const  MethodValue:  TMethod;
                                                              const  DefMethodValue:  TMethod;
                                                              var  Handled:  Boolean)  of  object


TWriteMethodPropertyEvent  is  the  prototype  for  the  TWriter.OnWriteMethodProperty
(379  )  event.   Writer  is  the  sender  of  the  event,  Instance  is  the  instance  that  is  being
streamed.  PropInfo is a pointer to the RTTI information for the property being written, and
MethodValue is the value of the method that the property was set to.  DefMethodCodeValue
is set to the default value of the property (Nil or the parent value).  Handled should be set
to True if the handler set the property succesfully.


TWriterProc  =  procedure(Writer:  TWriter)  of  object


The TWriterProc writer procedure is a callback procedure which will be used by a TPersis-
tent (318  ) descendent to write user properties from a stream during the streaming process.
The Writer argument is the writer object which can be used write properties to the stream.
2.3.3        Variables

AddDataModule  :  procedure(DataModule:  TDataModule)  of  object
                                                                 198

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                AddDataModule can be set by an IDE or a streaming mechanism to receive notification when
                a new instance of a TDataModule (280  ) descendent is created.


                ApplicationHandleException  :  procedure(Sender:  TObject)  of  object


                ApplicationHandleException can be set by an application object to handle any exceptions
                that may occur when a TDataModule (280  ) is created.


                ApplicationShowException  :  procedure(E:  Exception)  of  object


                Unused.


                GlobalNameSpace  :  IReadWriteSync


                An  interface  protecting  the  global  namespace.   Used  when  reading/writing  to  the  global
                namespace list during streaming of forms.


                MainThreadID  :  TThreadID


                ID of main thread.  Unused at this point.


                RegisterComponentsProc  :  procedure(const  Page:  String;ComponentClasses:  Array  of  TComponentClass)


                RegisterComponentsProc can be set by an IDE to be notified when new components are be-
                ing registered.  Application programmers should never have to set RegisterComponentsProc


                RegisterNoIconProc  :  procedure(ComponentClasses:  Array  of  TComponentClass)


                RegisterNoIconProc can be set by an IDE to be notified when new components are being
                registered, and which do not need an Icon in the component palette.  Application program-
                mers should never have to set RegisterComponentsProc


                RemoveDataModule  :  procedure(DataModule:  TDataModule)  of  object


                RemoveDataModule can be set by an IDE or a streaming mechanism to receive notification
                when an instance of a TDataModule (280  ) descendent is freed.


                WakeMainThread  :  TNotifyEvent  =  nil


                WakeMainThread is called by the TThread.synchronize (369  ) call.  It should alert the main
                program  thread  that  a  thread  is  waiting  for  synchronization.  The  call  is  executed  by  the
                thread, and should therefore NOT synchronize the thread, but should somehow signal the
                main thread that a thread is waiting for synchronization.  For example, by sending a message.
                2.4         Procedures  and  functions



                2.4.1        ActivateClassGroup

    Synopsis:    Activates a class group

Declaration:     function  ActivateClassGroup(AClass:  TPersistentClass)  :  TPersistentClass



                                                                                 199

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    Visibility:  default

Description:     ActivateClassGroup activates the group of classes to which AClass belongs.  The function
                returns the class that was last used to activate the class group.

                The  class  registration  and  streaming  mechanism  allows  to  organize  the  classes  in  groups.
                This allows an IDE to form groups of classes,  which can be enabled or disabled.  It is not
                needed at Run-Time.

       Errors:   If  AClass does not belong to a class group, an exception is raised.

    See also:    StartClassGroup (213  ), GroupDescendentsWith (204  ), ClassGroupOf (201  )
                2.4.2        BeginGlobalLoading

    Synopsis:    Not yet implemented

Declaration:     procedure  BeginGlobalLoading

    Visibility:   default

Description:     Not yet implemented
                2.4.3        BinToHex

    Synopsis:    Convert a binary buffer to a hexadecimal string

Declaration:     procedure  BinToHex(BinValue:  PChar;HexValue:  PChar;BinBufSize:  Integer)

    Visibility:   default

Description:     BinToHex converts the byte values in BinValue to a string consisting of 2-charachter hex-
                adecimal strings in HexValue.  BufSize specifies the length of  BinValue, which means that
                HexValue must have size 2*BufSize.

                For example a buffer containing the byte values 255 and 0 will be converted to FF00.

       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    HexToBin (205  )
                2.4.4        Bounds

    Synopsis:    Returns a TRect structure with the bounding rect of the given location and size.

Declaration:     function  Bounds(ALeft:  Integer;ATop:  Integer;AWidth:  Integer;
                                         AHeight:  Integer)  :  TRect

    Visibility:   default

Description:     Bounds returns a TRect (195  ) record with the given origin (ALeft,ATop) and dimensions
                (AWidth,AHeight) filled in.


                                                                                 200

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.5        CheckSynchronize

    Synopsis:    Check whether there are any synchronize calls in the synchronize queue.

Declaration:     function  CheckSynchronize(timeout:  LongInt)  :  Boolean

    Visibility:   default

Description:     CheckSynchronize should be called regularly by the main application thread to handle any
                TThread.synchronize (369  ) calls that may be waiting for execution by the main thread.

    See also:    TThread.synchronize (369  )
                2.4.6        ClassGroupOf

    Synopsis:    Returns the class group to which an instance or class belongs

Declaration:     function  ClassGroupOf(AClass:  TPersistentClass)  :  TPersistentClass
                function  ClassGroupOf(Instance:  TPersistent)  :  TPersistentClass

    Visibility:   default

Description:     ClassGroupOf returns the class group to which AClass or Instance belongs.

       Errors:   The result is Nil if no matching class group is found.

    See also:    StartClassGroup (213  ), ActivateClassGroup (199  ), GroupDescendentsWith (204  )
                2.4.7        CollectionsEqual

    Synopsis:    Returns True if two collections are equal.

Declaration:     function  CollectionsEqual(C1:  TCollection;C2:  TCollection)  :  Boolean
                function  CollectionsEqual(C1:  TCollection;C2:  TCollection;
                                                         Owner1:  TComponent;Owner2:  TComponent)
                                                           :  Boolean

    Visibility:   default

Description:     CollectionsEqual is not yet implemented.  It simply returns False
                2.4.8        EndGlobalLoading

    Synopsis:    Not yet implemented.

Declaration:     procedure  EndGlobalLoading

    Visibility:   default

Description:     Not yet implemented.

                                                                                 201

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.9        ExtractStrings

    Synopsis:    Split a string in different words.

Declaration:     function  ExtractStrings(Separators:  TSysCharSet;WhiteSpace:  TSysCharSet;
                                                      Content:  PChar;Strings:  TStrings)  :  Integer

    Visibility:   default

Description:     ExtractStrings splits Content (a null-terminated string) into words, and adds the words
                to  the  Strings  stringlist.  The  words  are  separated  by  Separators  and  any  characters  in
                whitespace  are  stripped  from  the  strings.   The  space  and  CR/LF  characters  are  always
                considered whitespace.

       Errors:   No length checking is performed on Content.  If no null-termination character is present, an
                access violation may occur.  Likewise, if Strings is not valid, an access violation may occur.
                2.4.10         FindClass

    Synopsis:    Returns the class pointer of a class with given name.

Declaration:     function  FindClass(const  AClassName:  String)  :  TPersistentClass

    Visibility:   default

Description:     FindClass  searches  for  the  class  named  ClassName  in  the  list  of  registered  classes  and
                returns a class pointer to the definition.  If no class with the given name could be found, an
                exception is raised.

                The GetClass (203  ) function does not raise an exception when it does not find the class, but
                returns a Nil pointer instead.

    See also:    RegisterClass (209  ), GetClass (203  )
                2.4.11         FindGlobalComponent

    Synopsis:    Callback used when a component must be found.

Declaration:     function  FindGlobalComponent(const  Name:  String)  :  TComponent

    Visibility:   default

Description:     FindGlobalComponent is a callback of type TFindGlobalComponent (191  ).  It can be set
                by the IDE when an unknown reference is found, to offer the user to redirect the link to a
                new component.

                It is a callback used to find a component in a global scope.  It is used when the streaming
                system  needs  to  find  a  component  which  is  not  part  of  the  component  which  is  currently
                being streamed.  It should return the component with name Name, or Nil if none is found.

    See also:    TFindGlobalComponent (191  )
                2.4.12         FindIdentToInt

    Synopsis:    Return the string to integer converter for an integer type

Declaration:     function  FindIdentToInt(AIntegerType:  Pointer)  :  TIdentToInt

    Visibility:   default



                                                                                 202

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     FindIdentToInt returns the handler that handles the conversion of a string representation
                to an integer that can be used in component streaming, when IdentToInt (205  ) is called.

       Errors:   Nil is returned if no handler is registered for the given type.
                2.4.13         FindIntToIdent

    Synopsis:    Return the integer to string converter for an integer type

Declaration:     function  FindIntToIdent(AIntegerType:  Pointer)  :  TIntToIdent

    Visibility:   default

Description:     FindIntToIdent returns the handler that handles the conversion of an integer to a string
                representation that can be used in component streaming, when IntToIdent (206  ) is called.

       Errors:   Nil is returned if no handler is registered for the given type.

    See also:    IntToIdent (206  ), TIntToIdent (192  ), FindIdentToInt (202  )
                2.4.14         FindNestedComponent

    Synopsis:    Finds the component with name path starting at the indicated root component.

Declaration:     function  FindNestedComponent(Root:  TComponent;APath:  String;
                                                              CStyle:  Boolean)  :  TComponent

    Visibility:   default

Description:     FindNestedComponent will descend through the list of owned components (starting at Root)
                and will return the component whose name path matches NamePath.  As a path separator
                the characters .  (dot), - (dash) and > (greater than) can be used

    See also:    GlobalFixupReferences (204  )
                2.4.15         GetClass

    Synopsis:    Returns the class pointer of a class with given name.

Declaration:     function  GetClass(const  AClassName:  String)  :  TPersistentClass

    Visibility:   default

Description:     GetClass searches for the class named ClassName in the list of registered classes and returns
                a  class  pointer  to  the  definition.   If  no  class  with  the  given  name  could  be  found,  Nil  is
                returned.

                The FindClass (202  ) function will raise an exception if the does not find the class.

    See also:    RegisterClass (209  ), GetClass (203  )

                                                                                 203

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.16         GetFixupInstanceNames

    Synopsis:    Returns  the  names  of  elements  that  need  to  be  resolved  for  the  root  component,  whose
                reference contains ReferenceRootName

Declaration:     procedure  GetFixupInstanceNames(Root:  TComponent;
                                                                   const  ReferenceRootName:  String;
                                                                   Names:  TStrings)

    Visibility:   default

Description:     GetFixupInstanceNames examines the list of unresolved references and returns the names
                of classes that contain unresolved references to the Root component in the list Names.  The
                list is not cleared prior to filling it.

    See also:    GetFixupReferenceNames (204  ), GlobalFixupReferences (204  )
                2.4.17         GetFixupReferenceNames

    Synopsis:    Returns the names of elements that need to be resolved for the root component.

Declaration:     procedure  GetFixupReferenceNames(Root:  TComponent;Names:  TStrings)

    Visibility:   default

Description:     GetFixupReferenceNames examines the list of unresolved references and returns the names
                of properties that must be resolved for the component Root in the list Names.  The list is not
                cleared prior to filling it.

    See also:    GetFixupInstanceNames (204  ), GlobalFixupReferences (204  )
                2.4.18         GlobalFixupReferences

    Synopsis:    Called to resolve unresolved references after forms are loaded.

Declaration:     procedure  GlobalFixupReferences

    Visibility:   default

Description:     GlobalFixupReferences  runs  over  the  list  of  unresolved  references  and  tries  to  resolve
                them.   This  routine  should  under  normal  circumstances  not  be  called  in  an  application
                programmer's code.  It is called automatically by the streaming system after a component
                has  been  instantiated  and  its  properties  read  from  a  stream.   It  will  attempt  to  resolve
                references to other global components.

    See also:    GetFixupReferenceNames (204  ), GetFixupInstanceNames (204  )
                2.4.19         GroupDescendentsWith

    Synopsis:    Add class to the group of another class.

Declaration:     procedure  GroupDescendentsWith(AClass:  TPersistentClass;
                                                                  AClassGroup:  TPersistentClass)

    Visibility:   default
                                                                                 204

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     GroupDescendentsWith adds AClass to the group that AClassGroup belongs to.  If AClassGroup
                belongs to more than 1 group, then it is added to the group which contains the nearest an-
                cestor.

                The  class  registration  and  streaming  mechanism  allows  to  organize  the  classes  in  groups.
                This allows an IDE to form groups of classes,  which can be enabled or disabled.  It is not
                needed at Run-Time.

       Errors:

    See also:    StartClassGroup (213  ), ActivateClassGroup (199  ), ClassGroupOf (201  )
                2.4.20         HexToBin

    Synopsis:    Convert a hexadecimal string to a binary buffer

Declaration:     function  HexToBin(HexValue:  PChar;BinValue:  PChar;BinBufSize:  Integer)
                                              :  Integer

    Visibility:   default

Description:     HexToBin scans the hexadecimal string representation in HexValue and transforms every 2
                character hexadecimal number to a byte and stores it in BinValue.  The buffer size is the
                size  of  the  binary  buffer.  Scanning  will  stop  if  the  size  of  the  binary  buffer  is  reached  or
                when an invalid character is encountered.  The return value is the number of stored bytes.

       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    BinToHex (200  )
                2.4.21         IdentToInt

    Synopsis:    Looks up an integer value in a integer-to-identifier map list.

Declaration:     function  IdentToInt(const  Ident:  String;var  Int:  LongInt;
                                                const  Map:  Array  of  TIdentMapEntry)  :  Boolean

    Visibility:   default

Description:     IdentToInt searches Map for an entry whose Name field matches Ident and returns the cor-
                responding integer value in Int.  If a match was found, the function returns True, otherwise,
                False is returned.

    See also:    TIdentToInt (192  ), TIntToIdent (192  ), IntToIdent (206  ), TIdentMapEntry (192  )
                2.4.22         InitComponentRes

    Synopsis:    Provided for Delphi compatibility only

Declaration:     function  InitComponentRes(const  ResName:  String;Instance:  TComponent)
                                                           :  Boolean

    Visibility:   default

Description:     This function is provided for Delphi compatibility.  It always returns false.

    See also:    ReadComponentRes (208  )

                                                                                 205

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.23         InitInheritedComponent

    Synopsis:    Initializes a component descending from RootAncestor

Declaration:     function  InitInheritedComponent(Instance:  TComponent;
                                                                   RootAncestor:  TClass)  :  Boolean

    Visibility:   default

Description:     InitInheritedComponent  should  be  called  from  a  constructor  to  read  properties  of  the
                component Instance from the streaming system.  The RootAncestor class is the root class
                from which Instance is a descendent.  This must be one of  TDatamodule, TCustomForm or
                TFrame.

                The function returns True if the properties were successfully read from a stream or False if
                some error occurred.

    See also:    ReadComponentRes (208  ), ReadComponentResEx (208  ), ReadComponentResFile (208  )
                2.4.24         IntToIdent

    Synopsis:    Looks up an identifier for an integer value in a identifier-to-integer map list.

Declaration:     function  IntToIdent(Int:  LongInt;var  Ident:  String;
                                                const  Map:  Array  of  TIdentMapEntry)  :  Boolean

    Visibility:   default

Description:     IdentToInt  searches  Map  for  an  entry  whose  Value  field  matches  Int  and  returns  the
                corresponding identifier in Ident.  If a match was found, the function returns True, otherwise,
                False is returned.

    See also:    TIdentToInt (192  ), TintToIdent (192  ), IdentToInt (205  ), TIdentMapEntry (192  )
                2.4.25         InvalidPoint

    Synopsis:    Check whether a point is invalid.

Declaration:     function  InvalidPoint(X:  Integer;Y:  Integer)  :  Boolean
                function  InvalidPoint(const  At:  TPoint)  :  Boolean
                function  InvalidPoint(const  At:  TSmallPoint)  :  Boolean

    Visibility:   default

Description:     InvalidPoint  returns  True  if  the  X  and  Y  coordinates  (of  the  TPoint  or  TSmallPoint
                records, if one of these versions is used) are -1.

    See also:    TPoint (194  ), TSmallPoint (196  ), PointsEqual (208  )
                2.4.26         LineStart

    Synopsis:    Finds the start of a line in Buffer before BufPos.

Declaration:     function  LineStart(Buffer:  PChar;BufPos:  PChar)  :  PChar

    Visibility:   default

Description:     LineStart reversely scans Buffer starting at BufPos for a linefeed character.  It returns a
                pointer at the linefeed character.



                                                                                 206

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.27         NotifyGlobalLoading

    Synopsis:    Not yet implemented.

Declaration:     procedure  NotifyGlobalLoading

    Visibility:   default

Description:     Not yet implemented.
                2.4.28         ObjectBinaryToText

    Synopsis:    Converts an object stream from a binary to a text format.

Declaration:     procedure  ObjectBinaryToText(Input:  TStream;Output:  TStream)

    Visibility:   default

Description:     ObjectBinaryToText reads an object stream in binary format from Input and writes the
                object stream in text format to Output.  No components are instantiated during the process,
                this is a pure conversion routine.

    See also:    ObjectTextToBinary (207  )
                2.4.29         ObjectResourceToText

    Synopsis:    Converts an object stream from a (windows) resource to a text format.

Declaration:     procedure  ObjectResourceToText(Input:  TStream;Output:  TStream)

    Visibility:   default

Description:     ObjectResourceToText reads the resource header from the Input stream and then passes
                the streams to ObjectBinaryToText (207  )

    See also:    ObjectBinaryToText (207  ), ObjectTextToResource (207  )
                2.4.30         ObjectTextToBinary

    Synopsis:    Converts an object stream from a text to a binary format.

Declaration:     procedure  ObjectTextToBinary(Input:  TStream;Output:  TStream)

    Visibility:   default

Description:     Converts an object stream from a text to a binary format.
                2.4.31         ObjectTextToResource

    Synopsis:    Converts an object stream from a text to a (windows) resource format.

Declaration:     procedure  ObjectTextToResource(Input:  TStream;Output:  TStream)

    Visibility:   default

Description:     ObjectTextToResource  reads  an  object  stream  in  text  format  from  Input  and  writes  a
                resource stream to Output.

                Note that for the current implementation of this method in Free Pascal, the output stream
                should support positioning.  (e.g.  it should not be a pipe)

    See also:    ObjectBinaryToText (207  ), ObjectResourceToText (207  )



                                                                                 207

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.32         Point

    Synopsis:    Returns a TPoint record with the given coordinates.

Declaration:     function  Point(AX:  Integer;AY:  Integer)  :  TPoint

    Visibility:   default

Description:     Point returns a TPoint (194  ) record with the given coordinates AX and AY filled in.

    See also:    TPoint (194  ), SmallPoint (212  ), Rect (209  ), Bounds (200  )
                2.4.33         PointsEqual

    Synopsis:    Check whether two TPoint variables are equal.

Declaration:     function  PointsEqual(const  P1:  TPoint;const  P2:  TPoint)  :  Boolean
                function  PointsEqual(const  P1:  TSmallPoint;const  P2:  TSmallPoint)
                                                   :  Boolean

    Visibility:   default

Description:     PointsEqual compares the P1 and P2 points (of type TPoint (194  ) or TSmallPoint (196  ))
                and returns True if the X and Y coordinates of the points are equal, or False otherwise.

    See also:    TPoint (194  ), TSmallPoint (196  ), InvalidPoint (206  )
                2.4.34         ReadComponentRes

    Synopsis:    Read component properties from a resource in the current module

Declaration:     function  ReadComponentRes(const  ResName:  String;Instance:  TComponent)
                                                           :  TComponent

    Visibility:   default

Description:     This function is provided for Delphi compatibility.  It always returns Nil.
                2.4.35         ReadComponentResEx

    Synopsis:    Read component properties from a resource in the specified module

Declaration:     function  ReadComponentResEx(HInstance:  THandle;const  ResName:  String)
                                                              :  TComponent

    Visibility:   default

Description:     This function is provided for Delphi compatibility.  It always returns Nil.
                2.4.36         ReadComponentResFile

    Synopsis:    Read component properties from a specified resource file

Declaration:     function  ReadComponentResFile(const  FileName:  String;
                                                                Instance:  TComponent)  :  TComponent

    Visibility:   default

                                                                                 208

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     ReadComponentResFile starts reading properties for Instance from the file FileName.  It
                creates a filestream from FileName and then calls the TStream.ReadComponentRes (337  )
                method to read the state of the component from the stream.

    See also:    TStream.ReadComponentRes (337  ), WriteComponentResFile (214  )
                2.4.37         Rect

    Synopsis:    Returns a TRect record with the given coordinates.

Declaration:     function  Rect(ALeft:  Integer;ATop:  Integer;ARight:  Integer;
                                      ABottom:  Integer)  :  TRect

    Visibility:   default

Description:     Rect returns a TRect (195  ) record with the given top-left (ALeft,ATop) and bottom-right
                (ABottom,ARight) corners filled in.

                No checking is done to see whether the coordinates are valid.

    See also:    TRect (195  ), Point (208  ), SmallPoint (212  ), Bounds (200  )
                2.4.38         RedirectFixupReferences

    Synopsis:    Redirects references under the root object from OldRootName to NewRootName

Declaration:     procedure  RedirectFixupReferences(Root:  TComponent;
                                                                       const  OldRootName:  String;
                                                                       const  NewRootName:  String)

    Visibility:   default

Description:     RedirectFixupReferences  examines  the  list  of  unresolved  references  and  replaces  refer-
                ences to a root object named OldRootName with references to root object NewRootName.

                An  application  programmer  should  never  need  to  call  RedirectFixupReferences.   This
                function can be used by an IDE to support redirection of broken component links.

    See also:    RemoveFixupReferences (212  )
                2.4.39         RegisterClass

    Synopsis:    Registers a class with the streaming system.

Declaration:     procedure  RegisterClass(AClass:  TPersistentClass)

    Visibility:   default

Description:     RegisterClass registers the class AClass in the streaming system.  After the class has been
                registered, it can be read from a stream when a reference to this class is encountered.

    See also:    RegisterClasses (210  ), RegisterClassAlias (210  ), RegisterComponents (210  ), UnregisterClass
                (213  )
                                                                                 209

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.40         RegisterClassAlias

    Synopsis:    Registers a class alias with the streaming system.

Declaration:     procedure  RegisterClassAlias(AClass:  TPersistentClass;
                                                              const  Alias:  String)

    Visibility:   default

Description:     RegisterClassAlias  registers  a  class  alias  in  the  streaming  system.   If  a  reference  to  a
                class Alias is encountered in a stream, then an instance of the class AClass will be created
                instead by the streaming code.

    See also:    RegisterClass (209  ), RegisterClasses (210  ), RegisterComponents (210  ), UnregisterClass (213  )
                2.4.41         RegisterClasses

    Synopsis:    Registers multiple classes with the streaming system.

Declaration:     procedure  RegisterClasses(AClasses:  Array  of  TPersistentClass)

    Visibility:   default

Description:     RegisterClasses registers the specified classes AClass in the streaming system.  After the
                classes have been registered, they can be read from a stream when a reference to this class
                is encountered.

    See also:    RegisterClass (209  ), RegisterClassAlias (210  ), RegisterComponents (210  ), UnregisterClass
                (213  )
                2.4.42         RegisterComponents

    Synopsis:    Registers components for the component palette.

Declaration:     procedure  RegisterComponents(const  Page:  String;
                                                              ComponentClasses:  Array  of  TComponentClass)

    Visibility:   default

Description:     RegisterComponents  registers  the  component  on  the  appropriate  component  page.   The
                component pages can be used by an IDE to display the known components so an application
                programmer may pick and use the components in his programs.

                Registercomponents  inserts  the  component  class  in  the  correct  component  page.   If  the
                RegisterComponentsProc procedure is set, this is called as well.  Note that this behaviour is
                different from Delphi's behaviour where an exception will be raised if the procedural variable
                is not set.

    See also:    RegisterClass (209  ), RegisterNoIcon (211  )
                2.4.43         RegisterFindGlobalComponentProc

    Synopsis:    Register a component searching handler

Declaration:     procedure  RegisterFindGlobalComponentProc
                                                                                    (AFindGlobalComponent:  TFindGlobalComponent)

    Visibility:   default
                                                                                 210

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     RegisterFindGlobalComponentProc registers a global component search callback AFindGlobalComponent.
                When FindGlobalComponent (202  ) is called, then this callback will be used to search for the
                component.

       Errors:   None.

    See also:    FindGlobalComponent (202  ), UnRegisterFindGlobalComponentProc (213  )
                2.4.44         RegisterInitComponentHandler

    Synopsis:    Register a component initialization handler

Declaration:     procedure  RegisterInitComponentHandler(ComponentClass:  TComponentClass;
                                                                               Handler:  TInitComponentHandler)

    Visibility:   default

Description:     RegisterInitComponentHandler registers a component initialization handler Handler for
                the  component  ComponentClass.   This  handler  will  be  used  to  initialize  descendents  of
                ComponentClass in the InitInheritedComponent (206  ) call.

    See also:    InitInheritedComponent (206  ), TInitComponentHandler (192  )
                2.4.45         RegisterIntegerConsts

    Synopsis:    Registers some integer-to-identifier mappings.

Declaration:     procedure  RegisterIntegerConsts(IntegerType:  Pointer;
                                                                   IdentToIntFn:  TIdentToInt;
                                                                   IntToIdentFn:  TIntToIdent)

    Visibility:   default

Description:     RegisterIntegerConsts  registers  a  pair  of  callbacks  to  be  used  when  an  integer  of  type
                IntegerType must be mapped to an identifier (using IntToIdentFn) or when an identifier
                must be mapper to an integer (using IdentToIntFn).

                Component programmers can use RegisterIntegerConsts to associate a series of identifier
                strings with integer values for a property.  A necessary condition is that the property should
                have a separate type declared using the type  integer syntax.  If a type of integer is defined
                in this way, an IDE can show symbolic names for the values of these properties.

                The  IntegerType  should  be  a  pointer  to  the  type  information  of  the  integer  type.   The
                IntToIdentFn and IdentToIntFn are two callbacks that will be used when converting be-
                tween the identifier and integer value and vice versa.  The functions IdentToInt (205  ) and
                IntToIdent (206  ) can be used to implement these callback functions.

    See also:    TIdentToInt (192  ), TIntToIdent (192  ), IdentToInt (205  ), IntToIdent (206  )
                2.4.46         RegisterNoIcon

    Synopsis:    Registers components that have no icon on the component palette.

Declaration:     procedure  RegisterNoIcon(ComponentClasses:  Array  of  TComponentClass)

    Visibility:   default

Description:     RegisterNoIcon performs the same function as RegisterComponents (210  ) except that it
                calls RegisterNoIconProc (199  ) instead of RegisterComponentsProc (199  )

    See also:    RegisterNoIconProc (199  ), RegisterComponents (210  )



                                                                                 211

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.47         RegisterNonActiveX

    Synopsis:    Register non-activex component.

Declaration:     procedure  RegisterNonActiveX(ComponentClasses:  Array  of  TComponentClass;
                                                              AxRegType:  TActiveXRegType)

    Visibility:   default

Description:     Not yet implemented in Free Pascal
                2.4.48         RemoveFixupReferences

    Synopsis:    Removes references to rootname from the fixup list.

Declaration:     procedure  RemoveFixupReferences(Root:  TComponent;const  RootName:  String)

    Visibility:   default

Description:     RemoveFixupReferences examines the list of unresolved references and removes references
                to a root object pointing at Root or a root component named RootName.

                An application programmer should never need to call RemoveFixupReferences.  This func-
                tion can be used by an IDE to support removal of broken component links.

    See also:    RedirectFixupReferences (209  )
                2.4.49         RemoveFixups

    Synopsis:    Removes Instance from the fixup list.

Declaration:     procedure  RemoveFixups(Instance:  TPersistent)

    Visibility:   default

Description:     RemoveFixups removes all entries for component Instance from the list of unresolved ref-
                erences.a

    See also:    RedirectFixupReferences (209  ), RemoveFixupReferences (212  )
                2.4.50         SmallPoint

    Synopsis:    Returns a TSmallPoint record with the given coordinates.

Declaration:     function  SmallPoint(AX:  SmallInt;AY:  SmallInt)  :  TSmallPoint

    Visibility:   default

Description:     SmallPoint returns a TSmallPoint (196  ) record with the given coordinates AX and AY filled
                in.

    See also:    TSmallPoint (196  ), Point (208  ), Rect (209  ), Bounds (200  )



                                                                                 212

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.51         StartClassGroup

    Synopsis:    Start new class group.

Declaration:     procedure  StartClassGroup(AClass:  TPersistentClass)

    Visibility:   default

Description:     StartClassGroup starts a new class group and adds AClass to it.

                The  class  registration  and  streaming  mechanism  allows  to  organize  the  classes  in  groups.
                This allows an IDE to form groups of classes,  which can be enabled or disabled.  It is not
                needed at Run-Time.

    See also:    GroupDescendentsWith (204  ), ActivateClassGroup (199  ), ClassGroupOf (201  )
                2.4.52         UnRegisterClass

    Synopsis:    Unregisters a class from the streaming system.

Declaration:     procedure  UnRegisterClass(AClass:  TPersistentClass)

    Visibility:   default

Description:     UnregisterClass  removes  the  class  AClass  from  the  class  definitions  in  the  streaming
                system.

    See also:    UnRegisterClasses (213  ), UnRegisterModuleClasses (214  ), RegisterClass (209  )
                2.4.53         UnRegisterClasses

    Synopsis:    Unregisters multiple classes from the streaming system.

Declaration:     procedure  UnRegisterClasses(AClasses:  Array  of  TPersistentClass)

    Visibility:   default

Description:     UnregisterClasses  removes  the  classes  in  AClasses  from  the  class  definitions  in  the
                streaming system.
                2.4.54         UnregisterFindGlobalComponentProc

    Synopsis:    Remove a previously registered component searching handler.

Declaration:     procedure  UnregisterFindGlobalComponentProc
                                                                                       (AFindGlobalComponent:  TFindGlobalComponent)

    Visibility:   default

Description:     UnRegisterFindGlobalComponentProc unregisters the previously registered global compo-
                nent search callback AFindGlobalComponent.  After this call, when FindGlobalComponent
                (202  ) is called, then this callback will be no longer be used to search for the component.

       Errors:   None.

    See also:    FindGlobalComponent (202  ), RegisterFindGlobalComponentProc (210  )
                                                                                 213

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.4.55         UnRegisterModuleClasses

    Synopsis:    Unregisters classes registered by module.

Declaration:     procedure  UnRegisterModuleClasses(Module:  HMODULE)

    Visibility:   default

Description:     UnRegisterModuleClasses unregisters all classes which reside in the module Module.  For
                each registered class, the definition pointer is checked to see whether it resides in the module,
                and if it does, the definition is removed.

    See also:    UnRegisterClass (213  ), UnRegisterClasses (213  ), RegisterClasses (210  )
                2.4.56         WriteComponentResFile

    Synopsis:    Write component properties to a specified resource file

Declaration:     procedure  WriteComponentResFile(const  FileName:  String;
                                                                   Instance:  TComponent)

    Visibility:   default

Description:     WriteComponentResFile starts writing properties of Instance to the file FileName.  It cre-
                ates a filestream from FileName and then calls TStream.WriteComponentRes (338  ) method
                to write the state of the component to the stream.

    See also:    TStream.WriteComponentRes (338  ), ReadComponentResFile (208  )
                2.5         EBitsError



                2.5.1        Description

                When  an  index  of  a  bit  in  a  TBits  (254  )  is  out  of  the  valid  range  (0  to  Count-1)  then  a
                EBitsError exception is raised.
                2.6         EClassNotFound



                2.6.1        Description

                When  the  streaming  system  needs  to  create  a  component,  it  looks  for  the  class  pointer
                (VMT)  in  the  list  of  registered  classes  by  its  name.   If  this  name  is  not  found,  then  an
                EClassNotFound is raised.
                2.7         EComponentError



                2.7.1        Description

                When an error occurs during the registration of a component, or when naming a component,
                then a EComponentError is raised.  Possible causes are:


                    1.  An name with an illegal character was assigned to a component.

                    2.  A component with the same name and owner already exists.

                    3.  The component registration system isn't set up properly.



                                                                                 214

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
2.8         EFCreateError



2.8.1        Description

When the operating system reports an error during creation of a new file in the Filestream
Constructor (285  ), a EFCreateError is raised.
2.9         EFilerError



2.9.1        Description

This  class  serves  as  an  ancestor  class  for  exceptions  that  are  raised  when  an  error  occurs
during component streaming.  A EFilerError exception is raised when a class is registered
twice.
2.10          EFOpenError



2.10.1         Description

When the operating system reports an error during the opening of a file in the Filestream
Constructor (285  ), a EFOpenError is raised.
2.11          EInvalidImage



2.11.1         Description

This exception is not used by Free Pascal but is provided for Delphi compatibility.
2.12          EInvalidOperation



2.12.1         Description

This exception is not used in Free Pascal, it is defined for Delphi compatibiliy purposes only.
2.13          EListError



2.13.1         Description

If an error occurs in one of the TList (301  ) or TStrings (351  ) methods, then a EListError
exception is raised.  This can occur in one of the following cases:


    1.  There is not enough memory to expand the list.

    2.  The list tried to grow beyond its maximal capacity.

    3.  An  attempt  was  made  to  reduce  the  capacity  of  the  list  below  the  current  element
        count.

    4.  An attempt was made to set the list count to a negative value.

    5.  A non-existent element of the list was referenced.  (i.e.  the list index was out of bounds)



                                                                 215

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
    6.  An attempt was made to move an item to a position outside the list's bounds.
2.14          EMethodNotFound



2.14.1         Description

This  exception  is  no  longer  used  in  the  streaming  system.   This  error  is  replaced  by  a
EReadError (216  ).
2.15          EOutOfResources



2.15.1         Description

This exception is not used in Free Pascal, it is defined for Delphi compatibiliy purposes only.
2.16          EParserError



2.16.1         Description

When an error occurs during the parsing of a stream, an EParserError is raised.  Usually
this indicates that an invalid token was found on the input stream, or the token read from
the stream wasn't the expected token.
2.17          EReadError



2.17.1         Description

If an error occurs when reading from a stream, a EReadError exception is raised.  Possible
causes for this are:


    1.  Not enough data is available when reading from a stream

    2.  The stream containing a component's data contains invalid data.  this will occurr only
        when reading a component from a stream.
2.18          EResNotFound



2.18.1         Description

This exception is not used by Free Pascal but is provided for Delphi compatibility.
2.19          EStreamError



2.19.1         Description

An EStreamError is raised when an error occurs during reading from or writng to a stream:
Possible causes are


    1.  Not enough data is available in the stream.



                                                                 216

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
    2.  Trying to seek beyond the beginning or end of the stream.

    3.  Trying to set the capacity of a memory stream and no memory is available.

    4.  Trying to write to a read-only stream, such as a resource stream.

    5.  Trying to read from a write-only stream.
2.20          EStringListError



2.20.1         Description

When an error occurs in one of the methods of TStrings (351  ) then an EStringListError
is raised.  This can have one of the following causes:


    1.  There is not enough memory to expand the list.

    2.  The list tried to grow beyond its maximal capacity.

    3.  A non-existent element of the list was referenced.  (i.e.  the list index was out of bounds)

    4.  An attempt was made to add a duplicate entry to a TStringList (347  ) when TStringList.AllowDuplicates
        (347  ) is False.
2.21          EThread



2.21.1         Description

Thread error exception.
2.22          EThreadDestroyCalled



2.22.1         Description

Exception raised when a thread is destroyed illegally.
2.23          EWriteError



2.23.1         Description

If  an  error  occurs  when  writing  to  a  stream,  a  EWriteError  exception  is  raised.  Possible
causes for this are:


    1.  The stream doesn't allow writing.

    2.  An error occurred when writing a property to a stream.


                                                                 217

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.24          IDesignerNotify



                2.24.1         Description

                IDesignerNotify  is  an  interface  that  can  be  used  to  communicate  changes  to  a  designer
                mechanism.  It offers functionality for detecting changes, and notifications when the compo-
                nent is destroyed.
                2.24.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  218       Modified            Notify that the component is modified.
                __218_______Notification________Notification_of_owner_changes______________________________________________________*
 *___________
                2.24.3         IDesignerNotify.Modified

    Synopsis:    Notify that the component is modified.

Declaration:     procedure  Modified

    Visibility:   default

Description:     Modified can be used to notify a designer of changes, indicating that components should
                be streamed.
                2.24.4         IDesignerNotify.Notification

    Synopsis:    Notification of owner changes

Declaration:     procedure  Notification(AnObject:  TPersistent;Operation:  TOperation)

    Visibility:   default

Description:     Notification is the interface counterpart of TComponent.Notification (268  ) which is used
                to communicate adds to the components.

    See also:    TComponent.Notification (268  )
                2.25          IInterfaceComponentReference



                2.25.1         Description

                IInterfaceComponentReference is an interface to return the component that implements
                a given interface.  It is implemented by TComponent (268  ).
                2.25.2         Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                __219_______GetComponent_____________Return_component_instance_____________________________________________________*
 *___________
                                                                                 218

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.25.3         IInterfaceComponentReference.GetComponent

    Synopsis:    Return component instance

Declaration:     function  GetComponent  :  TComponent

    Visibility:   default

Description:     GetComponent returns the component instance.

       Errors:   None.

    See also:    TComponent (268  )
                2.26          IInterfaceList



                2.26.1         Description

                IInterfaceList is an interface for maintaining a list of interfaces, strongly resembling the
                standard  TList  (301  )  class.   It  offers  the  same  list  of  public  methods  as  TList,  with  the
                exception that it uses interfaces instead of pointers.

                All interfaces in the list should descend from IUnknown.

                More  detailed  descriptions  of  how  the  various  methods  behave  can  be  found  in  the  TList
                reference.
                2.26.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  222       Add                   Add an interface to the list
                  221       Clear                 Clear the list
                  221       Delete                Remove an interface from the list
                  222       Exchange              Exchange 2 interfaces in the list
                  222       First                 Return the first non-empty interface in the list.
                  220       Get                   Retrieve an interface pointer from the list.
                  220       GetCapacity           Return the capacity of the list.
                  220       GetCount              Return the current number of elements in the list.
                  222       IndexOf               Return the index of an interface.
                  222       Insert                Insert an interface in the list.
                  223       Last                  Returns the last non-nil interface in the list.
                  223       Lock                  Lock the list
                  220       Put                   Write an item to the list
                  223       Remove                Remove an interface from the list
                  221       SetCapacity           Set the capacity of the list
                  221       SetCount              Set the number of items in the list
                __223_______Unlock________________Unlock_the_list._________________________________________________________________*
 *___________
                2.26.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  223       Capacity        rw           Capacity of the list
                  224       Count           rw           Current number of elements in the list.
                  224       Items           rw           Provides Index-based, sequential, access to the interfaces in
                _________________________________________the_list._________________________________________________________________*
 *___________
                                                                                 219

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.26.4         IInterfaceList.Get

    Synopsis:    Retrieve an interface pointer from the list.

Declaration:     function  Get(i:  Integer)  :  IUnknown

    Visibility:   default

Description:     Get returns the interface pointer at position i in the list.  It serves as the Read method for
                the Items (224  ) property.

    See also:    IInterfaceList.Items (224  ), TList.Items (307  )
                2.26.5         IInterfaceList.GetCapacity

    Synopsis:    Return the capacity of the list.

Declaration:     function  GetCapacity  :  Integer

    Visibility:   default

Description:     GetCapacity returns the current capacity of the list.  It serves as the Read method for the
                Capacity (223  ) property.

    See also:    IInterfaceList.Capacity (223  ), TList.Capacity (306  )
                2.26.6         IInterfaceList.GetCount

    Synopsis:    Return the current number of elements in the list.

Declaration:     function  GetCount  :  Integer

    Visibility:   default

Description:     It serves as the Read method for the Count (224  ) property.

    See also:    IInterfaceList.Count (224  ), TList.Count (307  )
                2.26.7         IInterfaceList.Put

    Synopsis:    Write an item to the list

Declaration:     procedure  Put(i:  Integer;item:  IUnknown)

    Visibility:   default

Description:     Put writes the interface Item at position I in the list.  It servers as the Write method for
                the Items (224  ) property.

    See also:    IInterfaceList.Items (224  ), TList.Items (307  )


                                                                                 220

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.26.8         IInterfaceList.SetCapacity

    Synopsis:    Set the capacity of the list

Declaration:     procedure  SetCapacity(NewCapacity:  Integer)

    Visibility:   default

Description:     SetCapacity sets the capacity of the list to NewCapacity.  It serves as the Write method
                for the Capacity (223  ) property.

    See also:    IInterfaceList.Capacity (223  ), TList.Capacity (306  )
                2.26.9         IInterfaceList.SetCount

    Synopsis:    Set the number of items in the list

Declaration:     procedure  SetCount(NewCount:  Integer)

    Visibility:   default

Description:     SetCount  sets  the  count  of  the  list  to  NewCount.  It  serves  as  the  Write  method  for  the
                Capacity (223  )

    See also:    IInterfaceList.Count (224  ), TList.Count (307  )
                2.26.10          IInterfaceList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear

    Visibility:   default

Description:     Clear removes all interfaces from the list.  All interfaces in the list will be cleared (i.e.  their
                reference count will decrease with 1)

    See also:    TList.Clear (302  )
                2.26.11          IInterfaceList.Delete

    Synopsis:    Remove an interface from the list

Declaration:     procedure  Delete(index:  Integer)

    Visibility:   default

Description:     Delete  removes  the  interface  at  position  Index  from  the  list.   It  does  this  by  explicitly
                clearing the interface and then removing the slot.

    See also:    TList.Clear (302  ), IInterfaceList.Add (222  ), IInterfaceList.Delete (221  ), IInterfaceList.Insert
                (222  )


                                                                                 221

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.26.12          IInterfaceList.Exchange

    Synopsis:    Exchange 2 interfaces in the list

Declaration:     procedure  Exchange(index1:  Integer;index2:  Integer)

    Visibility:   default

Description:     Exchange exchanges 2 interfaces in the list at locations index1 and Index2.

    See also:    TList.Exchange (303  ), IInterfaceList.Add (222  ), IInterfaceList.Delete (221  ), IInterfaceList.Insert
                (222  )
                2.26.13          IInterfaceList.First

    Synopsis:    Return the first non-empty interface in the list.

Declaration:     function  First  :  IUnknown

    Visibility:   default

Description:     First returns the first non-empty interface in the list.

    See also:    TList.First (304  ), IInterfaceList.IndexOf (222  ), IInterfaceList.Last (223  )
                2.26.14          IInterfaceList.IndexOf

    Synopsis:    Return the index of an interface.

Declaration:     function  IndexOf(item:  IUnknown)  :  Integer

    Visibility:   default

Description:     IndexOf returns the location in the list of the interface Item.  If there is no such interface
                in the list, then -1 is returned.

    See also:    TList.IndexOf (304  ), IInterfaceList.First (222  ), IInterfaceList.Last (223  )
                2.26.15          IInterfaceList.Add

    Synopsis:    Add an interface to the list

Declaration:     function  Add(item:  IUnknown)  :  Integer

    Visibility:   default

Description:     Add adds the interface Item to the list, and returns the position at which it has been added.

    See also:    TList.Add (302  ), IInterfaceList.Insert (222  ), IInterfaceList.Delete (221  )
                2.26.16          IInterfaceList.Insert

    Synopsis:    Insert an interface in the list.

Declaration:     procedure  Insert(i:  Integer;item:  IUnknown)

    Visibility:   default

Description:     Insert inserts the interface Item in the list, at position I, shifting all items one position.

    See also:    TList.Insert (304  ), IInterfaceList.Add (222  ), IInterfaceList.Delete (221  )



                                                                                 222

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.26.17          IInterfaceList.Last

    Synopsis:    Returns the last non-nil interface in the list.

Declaration:     function  Last  :  IUnknown

    Visibility:   default

Description:     Last returns the last non-empty interface in the list.

    See also:    TList.Last (305  ), IInterfaceList.First (222  ), IInterfaceList.IndexOf (222  )
                2.26.18          IInterfaceList.Remove

    Synopsis:    Remove an interface from the list

Declaration:     function  Remove(item:  IUnknown)  :  Integer

    Visibility:   default

Description:     Remove searches for the first occurrence of  Item in the list and deletes it.

    See also:    TList.Remove (305  ), IInterfaceList.Delete (221  ), IInterfaceList.IndexOf (222  )
                2.26.19          IInterfaceList.Lock

    Synopsis:    Lock the list

Declaration:     procedure  Lock

    Visibility:   default

Description:     Lock  locks  the  list  and  returns  an  instance  to  the  internal  list.   After  a  call  to  lock,  the
                object list can only be accessed by the current thread, untill UnLock (223  ) is called.

    See also:    TList.Lock (301  ), IInterfaceList.Unlock (223  )
                2.26.20          IInterfaceList.Unlock

    Synopsis:    Unlock the list.

Declaration:     procedure  Unlock

    Visibility:   default

Description:     Unlock unlocks a locked list.  After a call to UnLock, other lists are again able to access the
                list.

    See also:    TList.UnLock (301  ), IInterfaceList.Lock (223  )
                2.26.21          IInterfaceList.Capacity

    Synopsis:    Capacity of the list

Declaration:     Property  Capacity  :  Integer

    Visibility:   default

      Access:    Read,Write



                                                                                 223

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     Capacity is the maximum number of elements the list can hold without needing to reallocate
                memory for the list.  It can be set to improve speed when adding a lot of items to the list.

    See also:    TList.Capacity (306  ), IInterfaceList.Count (224  )
                2.26.22          IInterfaceList.Count

    Synopsis:    Current number of elements in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   default

      Access:    Read,Write

Description:     Count  is  the  current  number  of  elements  in  the  list.   Setting  it  to  a  larger  number  will
                allocate empty slots.  Setting it to a smaller number will clear any interfaces that fall outside
                the new border.

    See also:    IInterfaceList.Capacity (223  ), TList.Count (307  )
                2.26.23          IInterfaceList.Items

    Synopsis:    Provides Index-based, sequential, access to the interfaces in the list.

Declaration:     Property  Items[index:  Integer]:  IUnknown;  default

    Visibility:   default

      Access:    Read,Write

Description:     Items is the default property of the interface list and provides index-based array access to
                the interfaces in the list.  Allowed values for Index include 0 to Count-1

    See also:    IInterfaceList.Count (224  ), TList.Items (307  )
                2.27          IStreamPersist



                2.27.1         Description

                IStreamPersist defines an interface for object persistence streaming to a stream.  Any class
                implementing  this  interface  is  expected  to  be  able  to  save  or  load  it's  state  from  or  to  a
                stream.
                2.27.2         Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  225       LoadFromStream              Load persistent data from stream.
                __225_______SaveToStream________________Save_persistent_data_to_stream.____________________________________________*
 *___________


                                                                                 224

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.27.3         IStreamPersist.LoadFromStream

    Synopsis:    Load persistent data from stream.

Declaration:     procedure  LoadFromStream(Stream:  TStream)

    Visibility:   default

Description:     LoadFromStream is the method called when the object should load it's state from the stream
                stream.   It  should  be  able  to  read  the  data  which  was  written  using  the  SavetoStream
                method.

    See also:    TPersistent (318  ), TComponent (268  ), TStream (333  ), IStreamPersist.SaveToStream (225  )
                2.27.4         IStreamPersist.SaveToStream

    Synopsis:    Save persistent data to stream.

Declaration:     procedure  SaveToStream(Stream:  TStream)

    Visibility:   default

Description:     SaveFromStream is the method called when the object should load it's state from the stream
                stream.   The  data  written  by  this  method  should  be  readable  by  the  LoadFromStream
                method.

    See also:    TPersistent  (318  ),  TComponent  (268  ),  TStream  (333  ),  IStreamPersist.LoadFromStream
                (225  )
                2.28          IStringsAdapter



                2.28.1         Description

                Is not yet supported in Free Pascal.
                2.28.2         Method  overview

                __Page______Property___________________Description_________________________________________________________________*
 *___________
                  225       ReferenceStrings           Add a reference to the indicated strings.
                __225_______ReleaseStrings_____________Release_the_reference_to_the_strings._______________________________________*
 *___________
                2.28.3         IStringsAdapter.ReferenceStrings

    Synopsis:    Add a reference to the indicated strings.

Declaration:     procedure  ReferenceStrings(S:  TStrings)

    Visibility:   default
                2.28.4         IStringsAdapter.ReleaseStrings

    Synopsis:    Release the reference to the strings.

Declaration:     procedure  ReleaseStrings

    Visibility:   default



                                                                                 225

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.29          TAbstractOb jectReader



                2.29.1         Description

                The  Free  Pascal  streaming  mechanism,  while  compatible  with  Delphi's  mechanism,  differs
                from it in the sense that the streaming mechanism uses a driver class when streaming com-
                ponents.  The  TAbstractObjectReader  class  is  the  base  driver  class  for  reading  property
                values from streams.  It consists entirely of abstract methods, which must be implemented
                by descendent classes.

                Different streaming mechanisms can be implemented by making a descendent from TAbstractObjectReader.
                The TBinaryObjectReader (243  ) class is such a descendent class, which streams data in bi-
                nary (Delphi compatible) format.

                All methods described in this class, mustbe implemented by descendent classes.
                2.29.2         Method  overview

                __Page______Property___________________________Description_________________________________________________________*
 *___________
                  227       BeginComponent                     Marks the reading of a new component.
                  227       BeginProperty                      Marks the reading of a property value.
                  227       BeginRootComponent                 Starts the reading of the root component.
                  226       NextValue                          Returns the type of the next value in the stream.
                  228       Read                               Read raw data from stream
                  228       ReadBinary                         Read binary data from the stream.
                  229       ReadCurrency                       Read a currency value from the stream.
                  229       ReadDate                           Read a date value from the stream.
                  228       ReadFloat                          Read a float value from the stream.
                  229       ReadIdent                          Read an identifier from the stream.
                  230       ReadInt16                          Read a 16-bit integer from the stream.
                  231       ReadInt32                          Read a 32-bit integer from the stream.
                  231       ReadInt64                          Read a 64-bit integer from the stream.
                  230       ReadInt8                           Read an 8-bit integer from the stream.
                  231       ReadSet                            Reads a set from the stream.
                  229       ReadSingle                         Read a single (real-type) value from the stream.
                  232       ReadStr                            Read a shortstring from the stream
                  232       ReadString                         Read a string of type StringType from the stream.
                  227       ReadValue                          Reads the type of the next value.
                  232       ReadWideString                     Read a widestring value from the stream.
                  233       SkipComponent                      Skip till the end of the component.
                __233_______SkipValue__________________________Skip_the_current_value._____________________________________________*
 *___________
                2.29.3         TAbstractObjectReader.NextValue

    Synopsis:    Returns the type of the next value in the stream.

Declaration:     function  NextValue  :  TValueType;    Virtual;    Abstract

    Visibility:   public

Description:     This function should return the type of the next value in the stream, but should not read
                it, i.e.  the stream position should not be altered by this method.  This is used to 'peek' in
                the stream what value is next.

    See also:    TAbstractObjectReader.ReadValue (227  )

                                                                                 226

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.29.4         TAbstractObjectReader.ReadValue

    Synopsis:    Reads the type of the next value.

Declaration:     function  ReadValue  :  TValueType;    Virtual;    Abstract

    Visibility:   public

Description:     This function returns the type of the next value in the stream and reads it.  i.e.  after the
                call to this method, the stream is positioned to read the value of the type returned by this
                function.

    See also:    TAbstractObjectReader.ReadValue (227  )
                2.29.5         TAbstractObjectReader.BeginRootComponent

    Synopsis:    Starts the reading of the root component.

Declaration:     procedure  BeginRootComponent;    Virtual;    Abstract

    Visibility:   public

Description:     This  function  can  be  used  to  initialize  the  driver  class  for  reading  a  component.   It  is
                called  once  at  the  beginning  of  the  read  process,  and  is  immediatly  followed  by  a  call  to
                BeginComponent (227  ).

    See also:    TAbstractObjectReader.BeginComponent (227  )
                2.29.6         TAbstractObjectReader.BeginComponent

    Synopsis:    Marks the reading of a new component.

Declaration:     procedure  BeginComponent(var  Flags:  TFilerFlags;var  AChildPos:  Integer;
                                                        var  CompClassName:  String;var  CompName:  String)
                                                        ;    Virtual;    Abstract

    Visibility:   public

Description:     This method is called when the streaming process wants to start reading a new component.

                Descendent classes should override this method to read the start of a component new com-
                ponent definition and return the needed arguments.  Flags should be filled with any flags
                that  were  found  at  the  component  definition,  as  well  as  AChildPos.  The  CompClassName
                should be filled with the class name of the streamed component, and the CompName argument
                should be filled with the name of the component.

    See also:    TAbstractObjectReader.BeginRootComponent (227  ), TAbstractObjectReader.BeginProperty
                (227  )
                2.29.7         TAbstractObjectReader.BeginProperty

    Synopsis:    Marks the reading of a property value.

Declaration:     function  BeginProperty  :  String;    Virtual;    Abstract

    Visibility:   public



                                                                                 227

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     BeginProperty  is  called  by  the  streaming  system  when  it  wants  to  read  a  new  property.
                The  return  value  of  the  function  is  the  name  of  the  property  which  can  be  read  from  the
                stream.

    See also:    TAbstractObjectReader.BeginComponent (227  )
                2.29.8         TAbstractObjectReader.Read

    Synopsis:    Read raw data from stream

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public

Description:     Read is introduced for Delphi compatibility to read raw data from the component stream.
                This should not be used in production code as it will totally mess up the streaming.

    See also:    TBinaryObjectReader.Read (246  ), TReader.Read (323  )
                2.29.9         TAbstractObjectReader.ReadBinary

    Synopsis:    Read binary data from the stream.

Declaration:     procedure  ReadBinary(const  DestData:  TMemoryStream);    Virtual;    Abstract

    Visibility:   public

Description:     ReadBinary is called when binary data should be read from the stream (i.e.  after ReadValue
                (227  ) returned a valuetype of vaBinary).  The data should be stored in the DestData memory
                stream by descendent classes.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TAbstractObjectReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet
                (231  ), TabstractObjectReader.ReadStr (232  ), TabstractObjectReader.ReadString (232  )
                2.29.10          TAbstractObjectReader.ReadFloat

    Synopsis:    Read a float value from the stream.

Declaration:     function  ReadFloat  :  Extended;    Virtual;    Abstract

    Visibility:   public

Description:     ReadFloat is called by the streaming system when it wants to read a float from the stream
                (i.e.  after ReadValue (227  ) returned a valuetype of  vaExtended).  The return value should
                be the value of the float.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TAbstractObjectReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet
                (231  ), TabstractObjectReader.ReadStr (232  ), TabstractObjectReader.ReadString (232  )
                                                                                 228

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.29.11          TAbstractObjectReader.ReadSingle

    Synopsis:    Read a single (real-type) value from the stream.

Declaration:     function  ReadSingle  :  Single;    Virtual;    Abstract

    Visibility:   public

Description:     ReadSingle is called by the streaming system when it wants to read a single-type float from
                the stream (i.e.  after ReadValue (227  ) returned a valuetype of vaSingle).  The return value
                should be the value of the float.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TAbstractObjectReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet
                (231  ), TabstractObjectReader.ReadStr (232  ), TabstractObjectReader.ReadString (232  )
                2.29.12          TAbstractObjectReader.ReadCurrency

    Synopsis:    Read a currency value from the stream.

Declaration:     function  ReadCurrency  :  Currency;    Virtual;    Abstract

    Visibility:   public

Description:     ReadCurrency is called when a currency-typed value should be read from the stream.  This
                abstract method should be overidden by descendent classes, and should return the currency
                value read from the stream.

    See also:    TAbstractObjectWriter.WriteCurrency (236  )
                2.29.13          TAbstractObjectReader.ReadDate

    Synopsis:    Read a date value from the stream.

Declaration:     function  ReadDate  :  TDateTime;    Virtual;    Abstract

    Visibility:   public

Description:     ReadDate is called by the streaming system when it wants to read a date/time value from
                the stream (i.e.  after ReadValue (227  ) returned a valuetype of  vaDate).  The return value
                should  be  the  date/time  value.   (This  value  can  be  stored  as  a  float,  since  TDateTime  is
                nothing but a float.)

    See also:    TAbstractObjectReader.ReadFloat (228  ), TAbstractObjectReader.ReadSingle (229  ), TAb-
                stractObjectReader.ReadIdent (229  ), TAbstractObjectReader.ReadInt8 (230  ), TAbstractO-
                bjectReader.ReadInt16  (230  ),  TAbstractObjectReader.ReadInt32  (231  ),  TAbstractObjec-
                tReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.14          TAbstractObjectReader.ReadIdent

    Synopsis:    Read an identifier from the stream.

Declaration:     function  ReadIdent(ValueType:  TValueType)  :  String;    Virtual;    Abstract

    Visibility:   public



                                                                                 229

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     ReadIdent  is  called  by  the  streaming  system  if  it  expects  to  read  an  identifier  of  type
                ValueType from the stream after a call to ReadValue (227  ) returned vaIdent.  The identifier
                should be returned as a string.  Note that in some cases the identifier does not actually have
                to be in the stream;



                                                                       Table 2.16:

                                ValueType         Expected value
                                vaIdent           Read from stream.
                                vaNil             'Nil'.  This does not have to be read from the stream.
                                vaFalse           'False'.  This does not have to be read from the stream.
                                vaTrue            'True'.  This does not have to be read from the stream.
                                vaNull            'Null'.  This does not have to be read from the stream.
    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle  (229  ),  TAbstractObjectReader.ReadInt8  (230  ),  TAbstrac-
                tObjectReader.ReadInt16 (230  ), TAbstractObjectReader.ReadInt32 (231  ), TAbstractObjec-
                tReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.15          TAbstractObjectReader.ReadInt8

    Synopsis:    Read an 8-bit integer from the stream.

Declaration:     function  ReadInt8  :  ShortInt;    Virtual;    Abstract

    Visibility:   public

Description:     ReadInt8  is  called  by  the  streaming  process  if  it  expects  to  read  an  integer  value  with  a
                size of 8 bits (1 byte) from the stream (i.e.  after ReadValue (227  ) returned a valuetype of
                vaInt8).  The return value is the value if the integer.  Note that the size of the value in the
                stream does not actually have to be 1 byte.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt16 (230  ), TAbstractObjectReader.ReadInt32 (231  ), TAbstractObjec-
                tReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.16          TAbstractObjectReader.ReadInt16

    Synopsis:    Read a 16-bit integer from the stream.

Declaration:     function  ReadInt16  :  SmallInt;    Virtual;    Abstract

    Visibility:   public

Description:     ReadInt16 is called by the streaming process if it expects to read an integer value with a
                size of 16 bits (2 bytes) from the stream (i.e.  after ReadValue (227  ) returned a valuetype of
                vaInt16).  The return value is the value if the integer.  Note that the size of the value in the
                stream does not actually have to be 2 bytes.
                                                                                 230

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt32 (231  ), TAbstractObjec-
                tReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.17          TAbstractObjectReader.ReadInt32

    Synopsis:    Read a 32-bit integer from the stream.

Declaration:     function  ReadInt32  :  LongInt;    Virtual;    Abstract

    Visibility:   public

Description:     ReadInt32 is called by the streaming process if it expects to read an integer value with a
                size of 32 bits (4 bytes) from the stream (i.e.  after ReadValue (227  ) returned a valuetype of
                vaInt32).  The return value is the value of the integer.  Note that the size of the value in the
                stream does not actually have to be 4 bytes.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.18          TAbstractObjectReader.ReadInt64

    Synopsis:    Read a 64-bit integer from the stream.

Declaration:     function  ReadInt64  :  Int64;    Virtual;    Abstract

    Visibility:   public

Description:     ReadInt64  is  called  by  the  streaming  process  if  it  expects  to  read  an  int64  value  with  a
                size of 64 bits (8 bytes) from the stream (i.e.  after ReadValue (227  ) returned a valuetype of
                vaInt64).  The return value is the value if the integer.  Note that the size of the value in the
                stream does not actually have to be 8 bytes.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TabstractObjectReader.ReadSet (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.19          TAbstractObjectReader.ReadSet

    Synopsis:    Reads a set from the stream.

Declaration:     function  ReadSet(EnumType:  Pointer)  :  Integer;    Virtual;    Abstract

    Visibility:   public

Description:     This method is called by the streaming system if it expects to read a set from the stream
                (i.e.  after ReadValue (227  ) returned a valuetype of vaSet).  The return value is the contents
                of the set, encoded in a bitmask the following way:

                For  each  (enumerated)  value  in  the  set,  the  bit  corresponding  to  the  ordinal  value  of  the
                enumerated value should be set.  i.e.  as 1  shl  ord(value).



                                                                                 231

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TAbstractObjectReader.ReadInt64 (231  ), TabstractObjectReader.ReadStr
                (232  ), TabstractObjectReader.ReadString (232  )
                2.29.20          TAbstractObjectReader.ReadStr

    Synopsis:    Read a shortstring from the stream

Declaration:     function  ReadStr  :  String;    Virtual;    Abstract

    Visibility:   public

Description:     ReadStr is called by the streaming system if it expects to read a shortstring from the stream
                (i.e.  after ReadValue (227  ) returned a valuetype of vaLString,vaWstring or vaString).  The
                return value is the string.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TAbstractObjectReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet
                (231  ), TabstractObjectReader.ReadString (232  )
                2.29.21          TAbstractObjectReader.ReadString

    Synopsis:    Read a string of type StringType from the stream.

Declaration:     function  ReadString(StringType:  TValueType)  :  String;    Virtual
                                                ;    Abstract

    Visibility:   public

Description:     ReadStr is called by the streaming system if it expects to read a string from the stream (i.e.
                after  ReadValue  (227  )  returned  a  valuetype  of  vaLString,vaWstring  or  vaString).   The
                return value is the string.

    See also:    TAbstractObjectReader.ReadFloat  (228  ),  TAbstractObjectReader.ReadDate  (229  ),  TAb-
                stractObjectReader.ReadSingle (229  ), TAbstractObjectReader.ReadIdent (229  ), TAbstrac-
                tObjectReader.ReadInt8 (230  ), TAbstractObjectReader.ReadInt16 (230  ), TAbstractObjec-
                tReader.ReadInt32 (231  ), TAbstractObjectReader.ReadInt64 (231  ), TabstractObjectReader.ReadSet
                (231  ), TabstractObjectReader.ReadStr (232  )
                2.29.22          TAbstractObjectReader.ReadWideString

    Synopsis:    Read a widestring value from the stream.

Declaration:     function  ReadWideString  :  WideString;    Virtual;    Abstract

    Visibility:   public

Description:     ReadWideString is called when a widestring-typed value should be read from the stream.
                This abstract method should be overidden by descendent classes.

    See also:    TAbstractObjectWriter.WriteWideString (237  )


                                                                                 232

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.29.23          TAbstractObjectReader.SkipComponent

    Synopsis:    Skip till the end of the component.

Declaration:     procedure  SkipComponent(SkipComponentInfos:  Boolean);    Virtual
                                                      ;    Abstract

    Visibility:   public

Description:     This  method  is  used  to  skip  the  entire  declaration  of  a  component  in  the  stream.   Each
                descendent of TAbstractObjectReader should implement this in a way which is optimal for
                the implemented stream format.

    See also:    TAbstractObjectReader.BeginComponent (227  ), TAbstractObjectReader.SkipValue (233  )
                2.29.24          TAbstractObjectReader.SkipValue

    Synopsis:    Skip the current value.

Declaration:     procedure  SkipValue;    Virtual;    Abstract

    Visibility:   public

Description:     SkipValue should be used when skipping a value in the stream; The method should deter-
                mine the type of the value which should be skipped by itself, if this is necessary.

    See also:    TAbstractObjectReader.SkipComponent (233  )
                2.30          TAbstractOb jectWriter



                2.30.1         Description

                Abstract driver class for writing component data.
                2.30.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  234       BeginCollection                Start writing a collection.
                  234       BeginComponent                 Start writing a component
                  234       BeginList                      Start writing a list.
                  234       BeginProperty                  Start writing a property
                  234       EndList                        Mark the end of a list.
                  234       EndProperty                    Marks the end of writing of a property.
                  235       Write                          Write raw data to stream
                  235       WriteBinary                    Writes binary data to the stream.
                  235       WriteBoolean                   Writes a boolean value to the stream.
                  236       WriteCurrency                  Write a currency value to the stream
                  236       WriteDate                      Writes a date type to the stream.
                  235       WriteFloat                     Writes a float value to the stream.
                  236       WriteIdent                     Writes an identifier to the stream.
                  236       WriteInteger                   Writes an integer value to the stream
                  236       WriteMethodName                Writes a methodname to the stream.
                  237       WriteSet                       Writes a set value to the stream.
                  235       WriteSingle                    Writes a single-type real value to the stream.
                  237       WriteString                    Writes a string value to the stream.
                __237_______WriteWideString________________Write_a_widestring_value_to_the_stream__________________________________*
 *___________



                                                                                 233

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.30.3         TAbstractObjectWriter.BeginCollection

    Synopsis:    Start writing a collection.

Declaration:     procedure  BeginCollection;    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a collection.
                2.30.4         TAbstractObjectWriter.BeginComponent

    Synopsis:    Start writing a component

Declaration:     procedure  BeginComponent(Component:  TComponent;Flags:  TFilerFlags;
                                                        ChildPos:  Integer);    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a component
                2.30.5         TAbstractObjectWriter.BeginList

    Synopsis:    Start writing a list.

Declaration:     procedure  BeginList;    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a list.
                2.30.6         TAbstractObjectWriter.EndList

    Synopsis:    Mark the end of a list.

Declaration:     procedure  EndList;    Virtual;    Abstract

    Visibility:   public

Description:     Mark the end of a list.
                2.30.7         TAbstractObjectWriter.BeginProperty

    Synopsis:    Start writing a property

Declaration:     procedure  BeginProperty(const  PropName:  String);    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a property
                2.30.8         TAbstractObjectWriter.EndProperty

    Synopsis:    Marks the end of writing of a property.

Declaration:     procedure  EndProperty;    Virtual;    Abstract

    Visibility:   public

Description:     Marks the end of writing of a property.



                                                                                 234

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.30.9         TAbstractObjectWriter.Write

    Synopsis:    Write raw data to stream

Declaration:     procedure  Write(const  Buffer;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public

Description:     Write is introduced for Delphi compatibility to write raw data to the component stream.
                This should not be used in new production code as it will totally mess up the streaming.

    See also:    TBinaryObjectWriter.Write (251  ), TWriter.Write (376  )
                2.30.10          TAbstractObjectWriter.WriteBinary

    Synopsis:    Writes binary data to the stream.

Declaration:     procedure  WriteBinary(const  Buffer;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public

Description:     Writes binary data to the stream.
                2.30.11          TAbstractObjectWriter.WriteBoolean

    Synopsis:    Writes a boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a boolean value to the stream.
                2.30.12          TAbstractObjectWriter.WriteFloat

    Synopsis:    Writes a float value to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a float value to the stream.
                2.30.13          TAbstractObjectWriter.WriteSingle

    Synopsis:    Writes a single-type real value to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a single-type real value to the stream.

                                                                                 235

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.30.14          TAbstractObjectWriter.WriteCurrency

    Synopsis:    Write a currency value to the stream

Declaration:     procedure  WriteCurrency(const  Value:  Currency);    Virtual;    Abstract

    Visibility:   public

Description:     WriteCurrency is called when a currency-typed value should be written to the stream.  This
                abstract method should be overidden by descendent classes.

    See also:    TAbstractObjectReader.ReadCurrency (229  )
                2.30.15          TAbstractObjectWriter.WriteDate

    Synopsis:    Writes a date type to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a date type to the stream.
                2.30.16          TAbstractObjectWriter.WriteIdent

    Synopsis:    Writes an identifier to the stream.

Declaration:     procedure  WriteIdent(const  Ident:  String);    Virtual;    Abstract

    Visibility:   public

Description:     Writes an identifier to the stream.
                2.30.17          TAbstractObjectWriter.WriteInteger

    Synopsis:    Writes an integer value to the stream

Declaration:     procedure  WriteInteger(Value:  Int64);    Virtual;    Abstract

    Visibility:   public

Description:     Writes an integer value to the stream
                2.30.18          TAbstractObjectWriter.WriteMethodName

    Synopsis:    Writes a methodname to the stream.

Declaration:     procedure  WriteMethodName(const  Name:  String);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a methodname to the stream.

                                                                                 236

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.30.19          TAbstractObjectWriter.WriteSet

    Synopsis:    Writes a set value to the stream.

Declaration:     procedure  WriteSet(Value:  LongInt;SetType:  Pointer);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a set value to the stream.
                2.30.20          TAbstractObjectWriter.WriteString

    Synopsis:    Writes a string value to the stream.

Declaration:     procedure  WriteString(const  Value:  String);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a string value to the stream.
                2.30.21          TAbstractObjectWriter.WriteWideString

    Synopsis:    Write a widestring value to the stream

Declaration:     procedure  WriteWideString(const  Value:  WideString);    Virtual;    Abstract

    Visibility:   public

Description:     WriteCurrency is called when a currency-typed value should be written to the stream.  This
                abstract method should be overidden by descendent classes.

    See also:    TAbstractObjectReader.ReadWideString (232  )
                2.31          TBasicAction



                2.31.1         Description

                TBasicAction  implements  a  basic  action  class  from  which  all  actions  are  derived.   It  in-
                troduces all basic methods of an action, and implements functionality to maintain a list of
                clients, i.e.  components that are connected with this action.

                Do not create instances of  TBasicAction.  Instead, create a descendent class and create an
                instance of this class instead.
                2.31.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  238       Create                         Creates a new instance of a TBasicAction (237  ) class.
                  238       Destroy                        Destroys the action.
                  239       Execute                        Triggers the OnExecute (240  ) event
                  239       ExecuteTarget                  Executes the action on the Target object
                  238       HandlesTarget                  Determines whether Target can be handled by this action
                  239       RegisterChanges                Registers a new client with the action.
                  240       UnRegisterChanges              Unregisters a client from the list of clients
                  240       Update                         Triggers the OnUpdate (241  ) event
                __239_______UpdateTarget___________________Notify_client_controls_when_the_action_updates_itself.__________________*
 *___________
                                                                                 237

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.31.3         Property  overview

                __Page______Property_____________________Access_______Description__________________________________________________*
 *___________
                  240       ActionComponent              rw           Returns the component that initiated the action.
                  240       OnExecute                    rw           Event triggered when the action executes.
                __241_______OnUpdate_____________________rw___________Event_trigged_when_the_application_is_idle.__________________*
 *___________
                2.31.4         TBasicAction.Create

    Synopsis:    Creates a new instance of a TBasicAction (237  ) class.

Declaration:     constructor  Create(AOwner:  TComponent);    Override

    Visibility:   public

Description:     Create  calls  the  inherited  constructor,  and  then  initializes  the  list  of  clients  controls  (or
                action lists) by adding the AClient argument to the list of client controls.

                Under normal circumstances it should not be necessary to create a TBasicAction descendent
                manually, actions are created in an IDE.

    See also:    TBasicAction.Destroy (238  ), TBasicAction.AssignClient (237  )
                2.31.5         TBasicAction.Destroy

    Synopsis:    Destroys the action.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the list of client controls and then calls the inherited destructor.

                An application programmer should not call Destroy directly; Instead Free should be called,
                if it needs to be called at all.  Normally the controlling class (e.g.  a TActionList) will destroy
                the action.
                2.31.6         TBasicAction.HandlesTarget

    Synopsis:    Determines whether Target can be handled by this action

Declaration:     function  HandlesTarget(Target:  TObject)  :  Boolean;    Virtual

    Visibility:   public

Description:     HandlesTarget returns True if  Target is a valid client for this action and if so, if it is in a
                suitable state to execute the action.  An application programmer should never need to call
                HandlesTarget directly, it will be called by the action itself when needed.

                In TBasicAction this method is empty; descendent classes should override this method to
                implement appropriate checks.

    See also:    TBasicAction.UpdateTarget (239  ), TBasicAction.ExecuteTarget (239  )

                                                                                 238

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.31.7         TBasicAction.UpdateTarget

    Synopsis:    Notify client controls when the action updates itself.

Declaration:     procedure  UpdateTarget(Target:  TObject);    Virtual

    Visibility:   public

Description:     UpdateTarget should update the client control specified by Target when the action updates
                itself.  In TBasicAction, the implementation of UpdateTarget is empty.  Descendent classes
                should override and implement UpdateTarget to actually update the Target object.

                An  application  programmer  should  never  need  to  call  HandlesTarget  directly,  it  will  be
                called by the action itself when needed.

    See also:    TBasicAction.HandlesTarget (238  ), TBasicAction.ExecuteTarget (239  )
                2.31.8         TBasicAction.ExecuteTarget

    Synopsis:    Executes the action on the Target object

Declaration:     procedure  ExecuteTarget(Target:  TObject);    Virtual

    Visibility:   public

Description:     ExecuteTarget performs the action on the Target object.  In TBasicAction this method
                does nothing.  Descendent classes should implement the action to be performed.  For instance
                an action to post data in a dataset could call the Post method of the dataset.

                An application programmer should never call ExecuteTarget directly.

    See also:    TBasicAction.HandlesTarget (238  ), TBasicAction.ExecuteTarget (239  ), TBasicAction.Execute
                (239  )
                2.31.9         TBasicAction.Execute

    Synopsis:    Triggers the OnExecute (240  ) event

Declaration:     function  Execute  :  Boolean;    Dynamic

    Visibility:   public

Description:     Execute triggers the OnExecute event, if one is assigned.  It returns True if the event handler
                was called, False otherwise.
                2.31.10          TBasicAction.RegisterChanges

    Synopsis:    Registers a new client with the action.

Declaration:     procedure  RegisterChanges(Value:  TBasicActionLink)

    Visibility:   public

Description:     RegisterChanges adds Value to the list of clients.

    See also:    TBasicAction.UnregisterChanges (240  )

                                                                                 239

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.31.11          TBasicAction.UnRegisterChanges

    Synopsis:    Unregisters a client from the list of clients

Declaration:     procedure  UnRegisterChanges(Value:  TBasicActionLink)

    Visibility:   public

Description:     UnregisterChanges removes Value from the list of clients.  This is called for instance when
                the action is destroyed, or when the client is assigned a new action.

    See also:    TBasicAction.UnregisterChanges (240  ), TBasicAction.Destroy (238  )
                2.31.12          TBasicAction.Update

    Synopsis:    Triggers the OnUpdate (241  ) event

Declaration:     function  Update  :  Boolean;    Virtual

    Visibility:   public

Description:     Update  triggers  the  OnUpdate  event,  if  one  is  assigned.  It  returns  True  if  the  event  was
                triggered, or False if no event was assigned.

                Application programmers should never run Update directly.  The Update method is called
                automatically by the action mechanism; Normally this is in the Idle time of an application.
                An application programmer should assign the OnUpdate (241  ) event, and perform any checks
                in that handler.

    See also:    TBasicAction.OnUpdate (241  ), TBasicAction.Execute (239  ), TBAsicAction.UpdateTarget
                (239  )
                2.31.13          TBasicAction.ActionComponent

    Synopsis:    Returns the component that initiated the action.

Declaration:     Property  ActionComponent  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     ActionComponent is set to the component that caused the action to execute,  e.g.  a tool-
                button or a menu item.  The property is set just before the action executes, and is reset to
                nil after the action was executed.

    See also:    TBasicAction.Execute (239  ), TBasicAction.OnExecute (240  )
                2.31.14          TBasicAction.OnExecute

    Synopsis:    Event triggered when the action executes.

Declaration:     Property  OnExecute  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write



                                                                                 240

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     OnExecute  is  the  event  triggered  when  the  action  is  activated  (executed).   The  event  is
                triggered e.g.  when the user clicks e.g.  on a menu item or a button associated to the action.
                The application programmer should provide a OnExecute event handler to execute whatever
                code is necessary when the button is pressed or the menu item is chosen.

                Note that assigning an OnExecute handler will result in the Execute (239  ) method returning
                a True value.  Predefined actions (such as dataset actions) will check the result of  Execute
                and will not perform their normal task if the OnExecute handler was called.

    See also:    TBasicAction.Execute (239  ), TBasicAction.OnUpdate (241  )
                2.31.15          TBasicAction.OnUpdate

    Synopsis:    Event trigged when the application is idle.

Declaration:     Property  OnUpdate  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnUpdate is the event triggered when the application is idle, and the action is being updated.
                The OnUpdate event can be used to set the state of the action, for instance disable it if the
                action cannot be executed at this point in time.

    See also:    TBasicAction.Update (240  ), TBasicAction.OnExecute (240  )
                2.32          TBasicActionLink



                2.32.1         Description

                TBasicActionLink links an Action to its clients.  With each client for an action, a TBasicActionLink
                class is instantiated to handle the communication between the action and the client.  It passes
                events between the action and its clients, and thus presents the action with a uniform inter-
                face to the clients.

                An application programmer should never use a TBasicActionLink instance directly; They
                are created automatically when an action is associated with a component.  Component pro-
                grammers should create specialized descendents of  TBasicActionLink which communicate
                changes in the action to the component.
                2.32.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  242       Create          Creates a new instance of the TBasicActionLink class
                  242       Destroy         Destroys the TBasicActionLink instance.
                  242       Execute         Calls the action's Execute method.
                __243_______Update__________Calls_the_action's_Update_method_______________________________________________________*
 *___________
                2.32.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                  243       Action             rw           The action to which the link was assigned.
                __243_______OnChange___________rw___________Event_handler_triggered_when_the_action's_properties_change____________*
 *___________

                                                                                 241

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.32.4         TBasicActionLink.Create

    Synopsis:    Creates a new instance of the TBasicActionLink class

Declaration:     constructor  Create(AClient:  TObject);    Virtual

    Visibility:   public

Description:     Create creates a new instance of a TBasicActionLink and assigns AClient as the client of
                the link.

                Application programmers should never instantiate TBasicActionLink classes directly.  An
                instance is created automatically when an action is assigned to a control (client).

                Component programmers can override the create constructor to initialize further properties.

    See also:    TBasicActionLink.Destroy (242  )
                2.32.5         TBasicActionLink.Destroy

    Synopsis:    Destroys the TBasicActionLink instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  unregisters  the  TBasicActionLink  with  the  action,  and  then  calls  the  inherited
                destructor.

                Application programmers should never call Destroy directly.  If a link should be destroyed
                at all, the Free method should be called instead.

    See also:    TBasicActionLink.Create (242  )
                2.32.6         TBasicActionLink.Execute

    Synopsis:    Calls the action's Execute method.

Declaration:     function  Execute(AComponent:  TComponent)  :  Boolean;    Virtual

    Visibility:   public

Description:     Execute sets the ActionComponent (240  ) property of the associated Action (243  ) to AComponent
                and  then  calls  the  Action's  execute  (239  )  method.   After  the  action  has  executed,  the
                ActionComponent property is cleared again.

                The return value of the function is the return value of the Action's execute method.

                Application  programmers  should  never  call  Execute  directly.   This  method  will  be  called
                automatically when the associated control is activated.  (e.g.  a button is clicked on)

                Component programmers should call Execute whenever the action should be activated.

    See also:    TBasicActionLink.Action (243  ), TBasicAction.ActionComponent (240  ), TBasicAction.Execute
                (239  ), TBasicAction.onExecute (240  )


                                                                                 242

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.32.7         TBasicActionLink.Update

    Synopsis:    Calls the action's Update method

Declaration:     function  Update  :  Boolean;    Virtual

    Visibility:   public

Description:     Update calls the associated Action's Update (240  ) methoda.

                Component programmers can override the Update method to provide additional processing
                when the Update method occurs.
                2.32.8         TBasicActionLink.Action

    Synopsis:    The action to which the link was assigned.

Declaration:     Property  Action  :  TBasicAction

    Visibility:   public

      Access:    Read,Write

Description:     Action represents the Action (237  ) which was assigned to the client.  Setting this property
                will unregister the client at the old action (if one existed) and registers the client at the new
                action.

    See also:    TBasicAction (237  )
                2.32.9         TBasicActionLink.OnChange

    Synopsis:    Event handler triggered when the action's properties change

Declaration:     Property  OnChange  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnChange is the event triggered when the action's properties change.

                Application programmers should never need to assign this event.  Component programmers
                can assign this event to have a client control reflect any changes in an Action's properties.

    See also:    TBasicActionLink.Change (241  ), TBasicAction.Change (237  )
                2.33          TBinaryOb jectReader



                2.33.1         Description

                The TBinaryObjectReader class reads component data stored in binary form in a file.  For
                this,  it  overrides  or  implements  all  abstract  methods  from  TAbstractObjectReader  (226  ).
                No new functionality is added by this class, it is a driver class for the streaming system.
                                                                                 243

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.33.2         Method  overview

                __Page______Property___________________________Description_________________________________________________________*
 *___________
                  245       BeginComponent                     Start reading a component.
                  246       BeginProperty                      Start reading a property.
                  245       BeginRootComponent                 Start reading the root component.
                  244       Create                             Creates a new binary data reader instance.
                  244       Destroy                            Destroys the binary data reader.
                  245       NextValue                          Return the type of the next value.
                  246       Read                               Read raw data from stream
                  246       ReadBinary                         Start reading a binary value.
                  247       ReadCurrency                       Read a currency value from the stream.
                  247       ReadDate                           Read a date.
                  246       ReadFloat                          Read a float value
                  247       ReadIdent                          Read an identifier
                  247       ReadInt16                          Read a 16-bits integer.
                  248       ReadInt32                          Read a 32-bits integer.
                  248       ReadInt64                          Read a 64-bits integer.
                  247       ReadInt8                           Read an 8-bits integer.
                  248       ReadSet                            Read a set
                  246       ReadSingle                         Read a single-size float value
                  248       ReadStr                            Read a short string
                  249       ReadString                         Read a string
                  245       ReadValue                          Read the next value in the stream
                  249       ReadWideString                     Read a widestring value from the stream.
                  249       SkipComponent                      Skip a component's data
                __249_______SkipValue__________________________Skip_a_value's_data_________________________________________________*
 *___________
                2.33.3         TBinaryObjectReader.Create

    Synopsis:    Creates a new binary data reader instance.

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Create instantiates a new binary component data reader.  The Stream stream is the stream
                from which data will be read.  The BufSize argument is the size of the internal buffer that
                will be used by the reader.  This can be used to optimize the reading process.

    See also:    TAbstractObjectReader (226  )
                2.33.4         TBinaryObjectReader.Destroy

    Synopsis:    Destroys the binary data reader.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  frees  the  buffer  allocated  when  the  instance  was  created.   It  also  positions  the
                stream on the last used position in the stream (the buffering may cause the reader to read
                more bytes than were actually used.)

    See also:    TBinaryObjectReader.Create (244  )


                                                                                 244

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.33.5         TBinaryObjectReader.NextValue

    Synopsis:    Return the type of the next value.

Declaration:     function  NextValue  :  TValueType;    Override

    Visibility:   public

Description:     NextValue  returns  the  type  of  the  next  value  in  a  binary  stream,  but  does  not  read  the
                value.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.6         TBinaryObjectReader.ReadValue

    Synopsis:    Read the next value in the stream

Declaration:     function  ReadValue  :  TValueType;    Override

    Visibility:   public

Description:     NextValue reads the next value in a binary stream and returns the type of the read value.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.7         TBinaryObjectReader.BeginRootComponent

    Synopsis:    Start reading the root component.

Declaration:     procedure  BeginRootComponent;    Override

    Visibility:   public

Description:     BeginRootComponent starts reading the root component in a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.8         TBinaryObjectReader.BeginComponent

    Synopsis:    Start reading a component.

Declaration:     procedure  BeginComponent(var  Flags:  TFilerFlags;var  AChildPos:  Integer;
                                                        var  CompClassName:  String;var  CompName:  String)
                                                        ;    Override

    Visibility:   public

Description:     This  method  is  simply  the  implementation  for  a  binary  stream  of  the  abstract  method
                introduced in TAbstractObjectReader (226  )



                                                                                 245

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.33.9         TBinaryObjectReader.BeginProperty

    Synopsis:    Start reading a property.

Declaration:     function  BeginProperty  :  String;    Override

    Visibility:   public

Description:     This  method  is  simply  the  implementation  for  a  binary  stream  of  the  abstract  method
                introduced in TAbstractObjectReader (226  )
                2.33.10          TBinaryObjectReader.Read

    Synopsis:    Read raw data from stream

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Override

    Visibility:   public

Description:     Read is introduced for Delphi compatibility to read raw data from the component stream.
                This should not be used in production code as it will totally mess up the streaming.

    See also:    TAbstractObjectReader.Read (228  ), TReader.Read (323  )
                2.33.11          TBinaryObjectReader.ReadBinary

    Synopsis:    Start reading a binary value.

Declaration:     procedure  ReadBinary(const  DestData:  TMemoryStream);    Override

    Visibility:   public

Description:     ReadBinary reads a binary valye from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.12          TBinaryObjectReader.ReadFloat

    Synopsis:    Read a float value

Declaration:     function  ReadFloat  :  Extended;    Override

    Visibility:   public

Description:     ReadFloat reads a float value from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.13          TBinaryObjectReader.ReadSingle

    Synopsis:    Read a single-size float value

Declaration:     function  ReadSingle  :  Single;    Override

    Visibility:   public

Description:     ReadSingle reads a single-sized float value from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )



                                                                                 246

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.33.14          TBinaryObjectReader.ReadCurrency

    Synopsis:    Read a currency value from the stream.

Declaration:     function  ReadCurrency  :  Currency;    Override

    Visibility:   public

Description:     var>ReadCurrency reads a currency-typed value from a binary stream.  It is the implemen-
                tation of the method introduced in TAbstractObjectReader (226  ).

    See also:    TAbstractObjectReader.ReadCurrency (229  ), TBinaryObjectWriter.WriteCurrency (252  )
                2.33.15          TBinaryObjectReader.ReadDate

    Synopsis:    Read a date.

Declaration:     function  ReadDate  :  TDateTime;    Override

    Visibility:   public

Description:     ReadDate reads a date value from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.16          TBinaryObjectReader.ReadIdent

    Synopsis:    Read an identifier

Declaration:     function  ReadIdent(ValueType:  TValueType)  :  String;    Override

    Visibility:   public

Description:     ReadIdent reads an identifier from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.17          TBinaryObjectReader.ReadInt8

    Synopsis:    Read an 8-bits integer.

Declaration:     function  ReadInt8  :  ShortInt;    Override

    Visibility:   public

Description:     Read8Int reads an 8-bits signed integer from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.18          TBinaryObjectReader.ReadInt16

    Synopsis:    Read a 16-bits integer.

Declaration:     function  ReadInt16  :  SmallInt;    Override

    Visibility:   public
                                                                                 247

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     Read16Int reads a 16-bits signed integer from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.19          TBinaryObjectReader.ReadInt32

    Synopsis:    Read a 32-bits integer.

Declaration:     function  ReadInt32  :  LongInt;    Override

    Visibility:   public

Description:     Read32Int reads a 32-bits signed integer from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.20          TBinaryObjectReader.ReadInt64

    Synopsis:    Read a 64-bits integer.

Declaration:     function  ReadInt64  :  Int64;    Override

    Visibility:   public

Description:     Read64Int reads a 64-bits signed integer from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.21          TBinaryObjectReader.ReadSet

    Synopsis:    Read a set

Declaration:     function  ReadSet(EnumType:  Pointer)  :  Integer;    Override

    Visibility:   public

Description:     ReadSet reads a set from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.22          TBinaryObjectReader.ReadStr

    Synopsis:    Read a short string

Declaration:     function  ReadStr  :  String;    Override

    Visibility:   public

Description:     ReadStr reads a short string from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )

                                                                                 248

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.33.23          TBinaryObjectReader.ReadString

    Synopsis:    Read a string

Declaration:     function  ReadString(StringType:  TValueType)  :  String;    Override

    Visibility:   public

Description:     ReadStr reads a string of type StringType from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.33.24          TBinaryObjectReader.ReadWideString

    Synopsis:    Read a widestring value from the stream.

Declaration:     function  ReadWideString  :  WideString;    Override

    Visibility:   public

Description:     var>ReadWideString reads a widestring-typed value from a binary stream.  It is the imple-
                mentation of the method introduced in TAbstractObjectReader (226  ).

    See also:    TAbstractObjectReader.ReadWideString (232  ), TBinaryObjectWriter.WriteWideString (253  )
                2.33.25          TBinaryObjectReader.SkipComponent

    Synopsis:    Skip a component's data

Declaration:     procedure  SkipComponent(SkipComponentInfos:  Boolean);    Override

    Visibility:   public

Description:     SkipComponent skips the data of a component in a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  ).
                2.33.26          TBinaryObjectReader.SkipValue

    Synopsis:    Skip a value's data

Declaration:     procedure  SkipValue;    Override

    Visibility:   public

Description:     SkipComponent skips the data of the next value in a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (226  )
                2.34          TBinaryOb jectWriter



                2.34.1         Description

                Driver class which stores component data in binary form.


                                                                                 249

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.34.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  250       BeginCollection                Start writing a collection.
                  251       BeginComponent                 Start writing a component
                  251       BeginList                      Start writing a list.
                  251       BeginProperty                  Start writing a property
                  250       Create                         Creates a new instance of a binary object writer.
                  250       Destroy                        Destroys an instance of the binary object writer.
                  251       EndList                        Mark the end of a list.
                  251       EndProperty                    Marks the end of writing of a property.
                  251       Write                          Write raw data to stream
                  252       WriteBinary                    Writes binary data to the stream.
                  252       WriteBoolean                   Writes a boolean value to the stream.
                  252       WriteCurrency                  Write a currency-valued type to a stream
                  252       WriteDate                      Writes a date type to the stream.
                  252       WriteFloat                     Writes a float value to the stream.
                  253       WriteIdent                     Writes an identifier to the stream.
                  253       WriteInteger                   Writes an integer value to the stream.
                  253       WriteMethodName                Writes a methodname to the stream.
                  253       WriteSet                       Writes a set value to the stream.
                  252       WriteSingle                    Writes a single-type real value to the stream.
                  253       WriteString                    Writes a string value to the stream.
                __253_______WriteWideString________________Write_a_widestring-valued_type_to_a_stream______________________________*
 *___________
                2.34.3         TBinaryObjectWriter.Create

    Synopsis:    Creates a new instance of a binary object writer.

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Creates a new instance of a binary object writer.
                2.34.4         TBinaryObjectWriter.Destroy

    Synopsis:    Destroys an instance of the binary object writer.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys an instance of the binary object writer.
                2.34.5         TBinaryObjectWriter.BeginCollection

    Synopsis:    Start writing a collection.

Declaration:     procedure  BeginCollection;    Override

    Visibility:   public


                                                                                 250

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.34.6         TBinaryObjectWriter.BeginComponent

    Synopsis:    Start writing a component

Declaration:     procedure  BeginComponent(Component:  TComponent;Flags:  TFilerFlags;
                                                        ChildPos:  Integer);    Override

    Visibility:   public
                2.34.7         TBinaryObjectWriter.BeginList

    Synopsis:    Start writing a list.

Declaration:     procedure  BeginList;    Override

    Visibility:   public
                2.34.8         TBinaryObjectWriter.EndList

    Synopsis:    Mark the end of a list.

Declaration:     procedure  EndList;    Override

    Visibility:   public
                2.34.9         TBinaryObjectWriter.BeginProperty

    Synopsis:    Start writing a property

Declaration:     procedure  BeginProperty(const  PropName:  String);    Override

    Visibility:   public
                2.34.10          TBinaryObjectWriter.EndProperty

    Synopsis:    Marks the end of writing of a property.

Declaration:     procedure  EndProperty;    Override

    Visibility:   public
                2.34.11          TBinaryObjectWriter.Write

    Synopsis:    Write raw data to stream

Declaration:     procedure  Write(const  Buffer;Count:  LongInt);    Override

    Visibility:   public

Description:     Write is introduced for Delphi compatibility to write raw data to the component stream.
                This should not be used in new production code as it will totally mess up the streaming.

    See also:    TAbstractObjectWriter.Write (235  ), TWriter.Write (376  )


                                                                                 251

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.34.12          TBinaryObjectWriter.WriteBinary

    Synopsis:    Writes binary data to the stream.

Declaration:     procedure  WriteBinary(const  Buffer;Count:  LongInt);    Override

    Visibility:   public
                2.34.13          TBinaryObjectWriter.WriteBoolean

    Synopsis:    Writes a boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean);    Override

    Visibility:   public
                2.34.14          TBinaryObjectWriter.WriteFloat

    Synopsis:    Writes a float value to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended);    Override

    Visibility:   public
                2.34.15          TBinaryObjectWriter.WriteSingle

    Synopsis:    Writes a single-type real value to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single);    Override

    Visibility:   public
                2.34.16          TBinaryObjectWriter.WriteCurrency

    Synopsis:    Write a currency-valued type to a stream

Declaration:     procedure  WriteCurrency(const  Value:  Currency);    Override

    Visibility:   public

Description:     WriteCurrency writes a currency-typed value to a binary stream.  It is the implementation
                of the method introduced in TAbstractObjectWriter (233  ).

    See also:    TAbstractObjectWriter.WriteCurrency (236  )
                2.34.17          TBinaryObjectWriter.WriteDate

    Synopsis:    Writes a date type to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime);    Override

    Visibility:   public



                                                                                 252

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.34.18          TBinaryObjectWriter.WriteIdent

    Synopsis:    Writes an identifier to the stream.

Declaration:     procedure  WriteIdent(const  Ident:  String);    Override

    Visibility:   public
                2.34.19          TBinaryObjectWriter.WriteInteger

    Synopsis:    Writes an integer value to the stream.

Declaration:     procedure  WriteInteger(Value:  Int64);    Override

    Visibility:   public
                2.34.20          TBinaryObjectWriter.WriteMethodName

    Synopsis:    Writes a methodname to the stream.

Declaration:     procedure  WriteMethodName(const  Name:  String);    Override

    Visibility:   public
                2.34.21          TBinaryObjectWriter.WriteSet

    Synopsis:    Writes a set value to the stream.

Declaration:     procedure  WriteSet(Value:  LongInt;SetType:  Pointer);    Override

    Visibility:   public
                2.34.22          TBinaryObjectWriter.WriteString

    Synopsis:    Writes a string value to the stream.

Declaration:     procedure  WriteString(const  Value:  String);    Override

    Visibility:   public
                2.34.23          TBinaryObjectWriter.WriteWideString

    Synopsis:    Write a widestring-valued type to a stream

Declaration:     procedure  WriteWideString(const  Value:  WideString);    Override

    Visibility:   public

Description:     WriteWidestring writes a widestring-typed value to a binary stream.  It is the implemen-
                tation of the method introduced in TAbstractObjectWriter (233  ).

    See also:    TAbstractObjectWriter.WriteWidestring (237  )



                                                                                 253

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.35          TBits



                2.35.1         Description

                TBits can be used to store collections of bits in an indexed array.  This is especially useful
                for storing collections of booleans:  Normally the size of a boolean is the size of the smallest
                enumerated type, i.e.  1 byte.  Since a bit can take 2 values it can be used to store a boolean
                as well.  Since TBits can store 8 bits in a byte, it takes 8 times less space to store an array
                of booleans in a TBits class then it would take to stoe them in a conventional array.

                TBits introduces methods to store and retrieve bit values, apply masks, and search for bits.
                2.35.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  256       AndBits               Performs an and operation on the bits.
                  255       Clear                 Clears a particular bit.
                  256       Clearall              Clears all bits in the array.
                  254       Create                Creates a new bits collection.
                  255       Destroy               Destroys a bit collection
                  258       Equals                Determines whether the bits of 2 arrays are equal.
                  258       FindFirstBit          Find first bit with a particular value
                  259       FindNextBit           Searches the next bit with a particular value.
                  259       FindPrevBit           Searches the previous bit with a particular value.
                  257       Get                   Retrieve the value of a particular bit
                  255       GetFSize              Returns the number of records used to store the bits.
                  257       Grow                  Expands the bits array to the requested size.
                  257       NotBits               Performs a not operation on the bits.
                  259       OpenBit               Returns the position of the first bit that is set to False.
                  256       OrBits                Performs an or operation on the bits.
                  258       SetIndex              Sets  the  start  position  for  FindNextBit  (259  )  and  FindPrevBit
                                                  (259  )
                  255       SetOn                 Turn a particular bit on.
                __256_______XorBits_______________Performs_a_xor_operation_on_the_bits.____________________________________________*
 *___________
                2.35.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  260       Bits            rw           Access to all bits in the array.
                __260_______Size____________rw___________Current_size_of_the_array_of_bits.________________________________________*
 *___________
                2.35.4         TBits.Create

    Synopsis:    Creates a new bits collection.

Declaration:     constructor  Create(TheSize:  LongInt);    Virtual

    Visibility:   public

Description:     Create creates a new bit collection with initial size TheSize.  The size of the collection can
                be changed later on.

                All bits are initially set to zero.

    See also:    TBits.Destroy (255  )
                                                                                 254

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.35.5         TBits.Destroy

    Synopsis:    Destroys a bit collection

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy destroys a previously created bit collection and releases all memory used to store
                the bit collection.

                Destroy should never be called directly, Free should be used instead.

       Errors:   None.

    See also:    TBits.Create (254  )
                2.35.6         TBits.GetFSize

    Synopsis:    Returns the number of records used to store the bits.

Declaration:     function  GetFSize  :  LongInt

    Visibility:   public

Description:     GetFSize returns the number of records used to store the current number of bits.

       Errors:   None.

    See also:    TBits.Size (260  )
                2.35.7         TBits.SetOn

    Synopsis:    Turn a particular bit on.

Declaration:     procedure  SetOn(Bit:  LongInt)

    Visibility:   public

Description:     SetOn turns on the bit at position bit, i.e.  sets it to 1.  If  bit is at a position bigger than
                the current size, the collection is expanded to the required size using Grow (257  ).

       Errors:   If  bit  is  larger  than  the  maximum  allowed  bits  array  size  or  is  negative,  an  EBitsError
                (214  ) exception is raised.

    See also:    TBits.Bits (260  ), TBits.clear (255  )
                2.35.8         TBits.Clear

    Synopsis:    Clears a particular bit.

Declaration:     procedure  Clear(Bit:  LongInt)

    Visibility:   public

Description:     Clear  clears  the  bit  at  position  bit.  If  the  array  If  bit  is  at  a  position  bigger  than  the
                current size, the collection is expanded to the required size using Grow (257  ).

       Errors:   If  bit  is  larger  than  the  maximum  allowed  bits  array  size  or  is  negative,  an  EBitsError
                (214  ) exception is raised.

    See also:    TBits.Bits (260  ), TBits.clear (255  )



                                                                                 255

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.35.9         TBits.Clearall

    Synopsis:    Clears all bits in the array.

Declaration:     procedure  Clearall

    Visibility:   public

Description:     ClearAll  clears  all  bits  in  the  array,  i.e.  sets  them  to  zero.  ClearAll  works  faster  than
                clearing all individual bits, since it uses the packed nature of the bits.

       Errors:   None.

    See also:    TBits.Bits (260  ), TBits.clear (255  )
                2.35.10          TBits.AndBits

    Synopsis:    Performs an and operation on the bits.

Declaration:     procedure  AndBits(BitSet:  TBits)

    Visibility:   public

Description:     andbits performs an and operation on the bits in the array with the bits of array BitSet.
                If  BitSet contains less bits than the current array, then all bits which have no counterpart
                in BitSet are cleared.

       Errors:   None.

    See also:    TBits.clearall (256  ), TBits.orbits (256  ), TBits.xorbits (256  ), TBits.notbits (257  )
                2.35.11          TBits.OrBits

    Synopsis:    Performs an or operation on the bits.

Declaration:     procedure  OrBits(BitSet:  TBits)

    Visibility:   public

Description:     andbits performs an or operation on the bits in the array with the bits of array BitSet.

                If  BitSet contains less bits than the current array, then all bits which have no counterpart
                in BitSet are left untouched.

                If  the  current  array  contains  less  bits  than  BitSet  then  it  is  grown  to  the  size  of  BitSet
                before the or operation is performed.

       Errors:   None.

    See also:    TBits.clearall (256  ), TBits.andbits (256  ), TBits.xorbits (256  ), TBits.notbits (257  )
                2.35.12          TBits.XorBits

    Synopsis:    Performs a xor operation on the bits.

Declaration:     procedure  XorBits(BitSet:  TBits)

    Visibility:   public



                                                                                 256

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     XorBits performs a xor operation on the bits in the array with the bits of array BitSet.

                If  BitSet contains less bits than the current array, then all bits which have no counterpart
                in BitSet are left untouched.

                If  the  current  array  contains  less  bits  than  BitSet  then  it  is  grown  to  the  size  of  BitSet
                before the xor operation is performed.

       Errors:   None.

    See also:    TBits.clearall (256  ), TBits.andbits (256  ), TBits.orbits (256  ), TBits.notbits (257  )
                2.35.13          TBits.NotBits

    Synopsis:    Performs a not operation on the bits.

Declaration:     procedure  NotBits(BitSet:  TBits)

    Visibility:   public

Description:     NotBits performs a not operation on the bits in the array with the bits of array Bitset.

                If  BitSet contains less bits than the current array, then all bits which have no counterpart
                in BitSet are left untouched.

       Errors:   None.

    See also:    TBits.clearall (256  ), TBits.andbits (256  ), TBits.orbits (256  ), TBits.xorbits (256  )
                2.35.14          TBits.Get

    Synopsis:    Retrieve the value of a particular bit

Declaration:     function  Get(Bit:  LongInt)  :  Boolean

    Visibility:   public

Description:     Get returns True if the bit at position bit is set, or False if it is not set.

       Errors:   If  bit is not a valid bit index then an EBitsError (214  ) exception is raised.

    See also:    TBits.Bits (260  ), TBits.FindFirstBit (258  ), TBits.seton (255  )
                2.35.15          TBits.Grow

    Synopsis:    Expands the bits array to the requested size.

Declaration:     procedure  Grow(NBit:  LongInt)

    Visibility:   public

Description:     Grow  expands  the  bit  array  so  it  can  at  least  contain  nbit  bits.  If  nbit  is  less  than  the
                current size, nothing happens.

       Errors:   If there is not enough memory to complete the operation, then an EBitsError (214  )is raised.

    See also:    TBits.Size (260  )

                                                                                 257

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.35.16          TBits.Equals

    Synopsis:    Determines whether the bits of 2 arrays are equal.

Declaration:     function  Equals(BitSet:  TBits)  :  Boolean

    Visibility:   public

Description:     equals returns True if all the bits in BitSet are the same as the ones in the current BitSet;
                if not, False is returned.

                If the sizes of the two BitSets are different, the arrays are still reported equal when all the
                bits in the larger set, which are not present in the smaller set, are zero.

       Errors:   None.

    See also:    TBits.clearall (256  ), TBits.andbits (256  ), TBits.orbits (256  ), TBits.xorbits (256  )
                2.35.17          TBits.SetIndex

    Synopsis:    Sets the start position for FindNextBit (259  ) and FindPrevBit (259  )

Declaration:     procedure  SetIndex(Index:  LongInt)

    Visibility:   public

Description:     SetIndex  sets  the  search  start  position  forFindNextBit  (259  )  and  FindPrevBit  (259  )  to
                Index.  This means that these calls will start searching from position Index.

                This  mechanism  provides  an  alternative  to  FindFirstBit  (258  )  which  can  also  be  used  to
                position for the FindNextBit and FindPrevBit calls.

       Errors:   None.

    See also:    TBits.FindNextBit (259  ), TBits.FindPrevBit (259  ), TBits.FindFirstBit (258  ), TBits.OpenBit
                (259  )
                2.35.18          TBits.FindFirstBit

    Synopsis:    Find first bit with a particular value

Declaration:     function  FindFirstBit(State:  Boolean)  :  LongInt

    Visibility:   public

Description:     FindFirstBit searches for the first bit with value State.  It returns the position of this bit,
                or -1 if no such bit was found.

                The  search  starts  at  position  0  in  the  array.  If  the  first  search  returned  a  positive  result,
                the found position is saved, and the FindNextBit (259  ) and FindPrevBit (259  ) will use this
                position to resume the search.  To start a search from a certain position, the start position
                can be set with the SetIndex (258  ) instead.

       Errors:   None.

    See also:    TBits.FindNextBit (259  ),  TBits.FindPrevBit (259  ),  TBits.OpenBit (259  ),  TBits.SetIndex
                (258  )

                                                                                 258

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.35.19          TBits.FindNextBit

    Synopsis:    Searches the next bit with a particular value.

Declaration:     function  FindNextBit  :  LongInt

    Visibility:   public

Description:     FindNextBit  resumes  a  previously  started  search.   It  searches  for  the  next  bit  with  the
                value specified in the FindFirstBit (258  ).  The search is done towards the end of the array
                and starts at the position last reported by one of the Find calls or at the position set with
                SetIndex (258  ).

                If another bit with the same value is found, its position is returned.  If no more bits with the
                same value are present in the array, -1 is returned.

       Errors:   None.

    See also:    TBits.FindFirstBit (258  ),  TBits.FindPrevBit (259  ),  TBits.OpenBit (259  ),  TBits.SetIndex
                (258  )
                2.35.20          TBits.FindPrevBit

    Synopsis:    Searches the previous bit with a particular value.

Declaration:     function  FindPrevBit  :  LongInt

    Visibility:   public

Description:     FindPrevBit resumes a previously started search.  It searches for the previous bit with the
                value specified in the FindFirstBit (258  ).  The search is done towards the beginning of the
                array and starts at the position last reported by one of the Find calls or at the position set
                with SetIndex (258  ).

                If another bit with the same value is found, its position is returned.  If no more bits with the
                same value are present in the array, -1 is returned.

       Errors:   None.

    See also:    TBits.FindFirstBit (258  ), TBits.FindNextBit (259  ), TBits.OpenBit (259  ), TBits.SetIndex
                (258  )
                2.35.21          TBits.OpenBit

    Synopsis:    Returns the position of the first bit that is set to False.

Declaration:     function  OpenBit  :  LongInt

    Visibility:   public

Description:     OpenBit returns the position of the first bit whose value is 0 (False), or -1 if no open bit
                was found.  This call is equivalent to FindFirstBit(False), except that it doesn't set the
                position for the next searches.

       Errors:   None.

    See also:    TBits.FindFirstBit (258  ), TBits.FindPrevBit (259  ), TBits.FindFirstBit (258  ), TBits.SetIndex
                (258  )


                                                                                 259

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.35.22          TBits.Bits

    Synopsis:    Access to all bits in the array.

Declaration:     Property  Bits[Bit:  LongInt]:  Boolean;  default

    Visibility:   public

      Access:    Read,Write

Description:     Bits allows indexed access to all of the bits in the array.  It gives True if the bit is 1, False
                otherwise; Assigning to this property will set, respectively clear the bit.

       Errors:   If an index is specified which is out of the allowed range then an EBitsError (214  ) exception
                is raised.

    See also:    TBits.Size (260  )
                2.35.23          TBits.Size

    Synopsis:    Current size of the array of bits.

Declaration:     Property  Size  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     Size is the current size of the bit array.  Setting this property will adjust the size;  this is
                equivalent to calling Grow(Value-1)

       Errors:   If an invalid size (negative or too large) is specified, a EBitsError (214  ) exception is raised.

    See also:    TBits.Bits (260  )
                2.36          TCollection



                2.36.1         Description

                TCollection  implements  functionality  to  manage  a  collection  of  named  objects.  Each  of
                these objects needs to be a descendent of the TCollectionItem (265  ) class.  Exactly which
                type of object is managed can be seen from the TCollection.ItemClass (264  ) property.

                Normally, no TCollection is created directly.  Instead, a descendents of  TCollection and
                TCollectionItem (265  ) are created as a pair.

                                                                                 260

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.36.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  262       Add                   Creates and adds a new item to the collection.
                  262       Assign                Assigns one collection to another.
                  262       BeginUpdate           Start an update batch.
                  263       Clear                 Removes all items from the collection.
                  261       Create                Creates a new collection.
                  263       Delete                Delete an item from the collection.
                  261       Destroy               Destroys the collection and frees all the objects it manages.
                  263       EndUpdate             Ends an update batch.
                  264       FindItemID            Searches  for  an  Item  in  the  collection,  based  on  its  TCollection-
                                                  Item.ID (267  ) property.
                  264       Insert                Insert an item in the collection.
                __261_______Owner_________________Owner_of_the_collection._________________________________________________________*
 *___________
                2.36.3         Property  overview

                __Page______Property__________Access_______Description_____________________________________________________________*
 *___________
                  264       Count             r            Number of items in the collection.
                  264       ItemClass         r            Class pointer for each item in the collection.
                __265_______Items_____________rw___________Indexed_array_of_items_in_the_collection._______________________________*
 *___________
                2.36.4         TCollection.Create

    Synopsis:    Creates a new collection.

Declaration:     constructor  Create(AItemClass:  TCollectionItemClass)

    Visibility:   public

Description:     Create instantiates a new instance of the TCollection class which will manage objects of
                class AItemClass.  It creates the list used to hold all objects, and stores the AItemClass for
                the adding of new objects to the collection.

    See also:    TCollection.ItemClass (264  ), TCollection.Destroy (261  )
                2.36.5         TCollection.Destroy

    Synopsis:    Destroys the collection and frees all the objects it manages.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy first clears the collection, and then frees all memory allocated to this instance.

                Don't call Destroy directly, call Free instead.

    See also:    TCollection.Create (261  )
                2.36.6         TCollection.Owner

    Synopsis:    Owner of the collection.

Declaration:     function  Owner  :  TPersistent
                                                                                 261

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    Visibility:  public

Description:     Owner returns a reference to the owner of the collection.  This property is required by the
                object inspector to be able to show the collection.
                2.36.7         TCollection.Add

    Synopsis:    Creates and adds a new item to the collection.

Declaration:     function  Add  :  TCollectionItem

    Visibility:   public

Description:     Add  instantiates  a  new  item  of  class  TCollection.ItemClass  (264  )  and  adds  it  to  the  list.
                The newly created object is returned.

    See also:    TCollection.ItemClass (264  ), TCollection.Clear (263  )
                2.36.8         TCollection.Assign

    Synopsis:    Assigns one collection to another.

Declaration:     procedure  Assign(Source:  TPersistent);    Override

    Visibility:   public

Description:     Assign assigns the contents of one collection to another.  It does this by clearing the items
                list, and adding as much elements as there are in the Source collection;  it assigns to each
                created element the contents of it's counterpart in the Source element.

                Two collections cannot be assigned to each other if instances of the ItemClass classes cannot
                be assigned to each other.

       Errors:   If the objects in the collections cannot be assigned to one another, then an EConvertError
                is raised.

    See also:    TPersistent.Assign (318  ), TCollectionItem (265  )
                2.36.9         TCollection.BeginUpdate

    Synopsis:    Start an update batch.

Declaration:     procedure  BeginUpdate;    Virtual

    Visibility:   public

Description:     BeginUpdate is called at the beginning of a batch update.  It raises the update count with
                1.

                Call BeginUpdate at the beginning of a series of operations that will change the state of the
                collection.  This will avoid the call to TCollection.Update (260  ) for each operation.  At the
                end of the operations, a corresponding call to EndUpdate must be made.  It is best to do this
                in the context of a Try  ...    finally block:


                With  MyCollection  Do
                       try
                          BeginUpdate;
                          //  Some  Lengthy  operations



                                                                                 262

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                      finally
                         EndUpdate;
                      end;


                This insures that the number of calls to BeginUpdate always matches the number of calls to
                TCollection.EndUpdate (263  ), even in case of an exception.

    See also:    TCollection.EndUpdate (263  ), TCollection.Changed (260  ), TCollection.Update (260  )
                2.36.10          TCollection.Clear

    Synopsis:    Removes all items from the collection.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear  will  clear  the  collection,  i.e.  each  item  in  the  collection  is  destroyed  and  removed
                from memory.  After a call to Clear, Count is zero.

    See also:    TCollection.Add (262  ), TCollectionItem.Destroy (266  ), TCollection.Destroy (261  )
                2.36.11          TCollection.EndUpdate

    Synopsis:    Ends an update batch.

Declaration:     procedure  EndUpdate;    Virtual

    Visibility:   public

Description:     EndUpdate signals the end of a series of operations that change the state of the collection,
                possibly triggering an update event.  It does this by decreasing the update count with 1 and
                calling  TCollection.Changed  (260  )  it  should  always  be  used  in  conjunction  with  TCollec-
                tion.BeginUpdate (262  ), preferably in the Finally section of a Try  ...    Finally block.

    See also:    TCollection.BeginUpdate (262  ), TCollection.Changed (260  ), TCollection.Update (260  )
                2.36.12          TCollection.Delete

    Synopsis:    Delete an item from the collection.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete deletes the item at (zero based) position Index from the collection.  This will result
                in a cnDeleted notification.

       Errors:   If an invalid index is specified, an exception is raised.

    See also:    TCollection.Items (265  ), TCollection.Insert (264  ), TCollection.Clear (263  )

                                                                                 263

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.36.13          TCollection.Insert

    Synopsis:    Insert an item in the collection.

Declaration:     function  Insert(Index:  Integer)  :  TCollectionItem

    Visibility:   public

Description:     Insert creates a new item instance and inserts it in the collection at position Index, and
                returns the new instance.

                In contrast, TCollection.Add (262  ) adds a new item at the end.

       Errors:   None.

    See also:    TCollection.Add (262  ), TCollection.Delete (263  ), TCollection.Items (265  )
                2.36.14          TCollection.FindItemID

    Synopsis:    Searches for an Item in the collection, based on its TCollectionItem.ID (267  ) property.

Declaration:     function  FindItemID(ID:  Integer)  :  TCollectionItem

    Visibility:   public

Description:     FindItemID  searches  through  the  collection  for  the  item  that  has  a  value  of  ID  for  its
                TCollectionItem.ID (267  ) property, and returns the found item.  If no such item is found in
                the collection, Nil is returned.

                The routine performs a linear search, so this can be slow on very large collections.

    See also:    TCollection.Items (265  ), TCollectionItem.ID (267  )
                2.36.15          TCollection.Count

    Synopsis:    Number of items in the collection.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read

Description:     Count contains the number of items in the collection.

 Remark:          The  items  in  the  collection  are  identified  by  their  TCollectionItem.Index  (267  )  property,
                which is a zero-based index, meaning that it can take values between 0 and Count.

    See also:    TCollectionItem.Index (267  ), TCollection.Items (265  )
                2.36.16          TCollection.ItemClass

    Synopsis:    Class pointer for each item in the collection.

Declaration:     Property  ItemClass  :  TCollectionItemClass

    Visibility:   public

      Access:    Read


                                                                                 264

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     ItemClass is the class pointer with which each new item in the collection is created.  It is
                the value that was passed to the collection's constructor when it was created, and does not
                change during the lifetime of the collection.

    See also:    TCollectionItem (265  ), TCollection.Items (265  )
                2.36.17          TCollection.Items

    Synopsis:    Indexed array of items in the collection.

Declaration:     Property  Items[Index:  Integer]:  TCollectionItem

    Visibility:   public

      Access:    Read,Write

Description:     Items provides indexed access to the items in the collection.  Since the array is zero-based,
                Index should be an integer between 0 and Count-1.

                It  is  possible  to  set  or  retrieve  an  element  in  the  array.   When  setting  an  element  of  the
                array, the object that is assigned should be compatible with the class of the objects in the
                collection, as given by the TCollection.ItemClass (264  ) property.

                Adding an element to the array can be done with the TCollection.Add (262  ) method.  The
                array can be cleared with the TCollection.Clear (263  ) method.  Removing an element of the
                array should be done by freeing that element.

    See also:    TCollection.Count  (264  ),  TCollection.ItemClass  (264  ),  TCollection.Clear  (263  ),  TCollec-
                tion.Add (262  )
                2.37          TCollectionItem



                2.37.1         Description

                TCollectionItem and TCollection (260  ) form a pair of base classes that manage a collection
                of named objects.  The TCollectionItem is the named object that is managed, it represents
                one  item  in  the  collection.   An  item  in  the  collection  is  represented  by  three  properties:
                TCollectionItem.DisplayName (267  ), TCollection.Index (260  ) and TCollectionItem.ID (267  ).

                A  TCollectionItem  object  is  never  created  directly.   To  manage  a  set  of  named  items,
                it is necessary to make a descendent of  TCollectionItem to which needed properties and
                methods are added.  This descendant can then be managed with a TCollection (260  ) class.
                The managing collection will create and destroy it's items by itself, it should therefore never
                be necessary to create TCollectionItem descendents manually.
                2.37.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  266       Create          Creates a new instance of this collection item.
                __266_______Destroy_________Destroyes_this_collection_item.________________________________________________________*
 *___________


                                                                                 265

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.37.3         Property  overview

                __Page______Property______________Access_______Description_________________________________________________________*
 *___________
                  266       Collection            rw           Pointer to the collection managing this item.
                  267       DisplayName           rw           Name of the item, displayed in the object inspector.
                  267       ID                    r            Initial index of this item.
                  267       Index                 rw           Index  of  the  item  in  its  managing  collection  TCollec-
                _______________________________________________tion.Items_(265__)_property.________________________________________*
 *___________
                2.37.4         TCollectionItem.Create

    Synopsis:    Creates a new instance of this collection item.

Declaration:     constructor  Create(ACollection:  TCollection);    Virtual

    Visibility:   public

Description:     Create instantiates a new item in a TCollection (260  ).  It is called by the TCollection.Add
                (262  ) function and should under normal circumstances never be called directly.  called

    See also:    TCollectionItem.Destroy (266  )
                2.37.5         TCollectionItem.Destroy

    Synopsis:    Destroyes this collection item.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy removes the item from the managing collection and Destroys the item instance.

                This is the only way to remove items from a collection;

    See also:    TCollectionItem.Create (266  )
                2.37.6         TCollectionItem.Collection

    Synopsis:    Pointer to the collection managing this item.

Declaration:     Property  Collection  :  TCollection

    Visibility:   public

      Access:    Read,Write

Description:     Collection points to the collection managing this item.  This property can be set to point
                to a new collection.  If this is done, the old collection will be notified that the item should
                no longer be managed, and the new collection is notified that it should manage this item as
                well.

    See also:    TCollection (260  )


                                                                                 266

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.37.7         TCollectionItem.ID

    Synopsis:    Initial index of this item.

Declaration:     Property  ID  :  Integer

    Visibility:   public

      Access:    Read

Description:     ID  is  the  initial  value  of  TCollectionItem.Index  (267  );  it  doesn't  change  after  the  index
                changes.  It can be used to uniquely identify the item.  The ID property doesn't change as
                items are added and removed from the collection.

                While the TCollectionItem.Index (267  ) property forms a continuous series, ID does not.  If
                items are removed from the collection, their ID is not used again, leaving gaps.  Only when
                the collection is initialiiy created, the ID and Index properties will be equal.

    See also:    TCollection.Items (265  ), TCollectionItem.Index (267  )
                2.37.8         TCollectionItem.Index

    Synopsis:    Index of the item in its managing collection TCollection.Items (265  ) property.

Declaration:     Property  Index  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Index is the current index of the item in its managing collection's TCollection.Items (265  )
                property.  This property may change as items are added and removed from the collection.

                The index of an item is zero-based, i.e.  the first item has index zero.  The last item has index
                Count-1 where Count is the number of items in the collection.

                The Index property of the items in a collection form a continuous series ranging from 0 to
                Count-1.  The TCollectionItem.ID (267  ) property does not form a continuous series, but can
                also be used to identify an item.

    See also:    TCollectionItem.ID (267  ), TCollection.Items (265  )
                2.37.9         TCollectionItem.DisplayName

    Synopsis:    Name of the item, displayed in the object inspector.

Declaration:     Property  DisplayName  :  String

    Visibility:   public

      Access:    Read,Write

Description:     DisplayName contains the name of this item as shown in the object inspector.  For TCollectionItem
                this returns always the class name of the managing collection, followed by the index of the
                item.

                TCollectionItem  does  not  implement  any  functionality  to  store  the  DisplayName  prop-
                erty.   The  property  can  be  set,  but  this  will  have  no  effect  other  than  that  the  manag-
                ing  collection  is  notified  of  a  change.  The  actual  displayname  will  remain  unchanged.  To
                store the DisplayName property,TCollectionItem descendants should override the TCollec-
                tionItem.SetDisplayName (265  ) and TCollectionItem.GetDisplayName (265  ) to add storage
                functionality.



                                                                                 267

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________
See also:    TCollectionItem.Index (267  ), TCollectionItem.ID (267  ), TCollectionItem.GetDisplayName
            (265  ), TCollectionItem.SetDisplayName (265  )
            2.38          TComponent



            2.38.1         Description

            TComponent  is  the  base  class  for  any  set  of  classes  that  needs  owner-owned  functionality,
            and which needs support for property streaming.  All classes that should be handled by an
            IDE (Integrated Development Environment) must descend from TComponent, as it includes
            all support for streaming all its published properties.

            Components can 'own' other components.  TComponent introduces methods for enumerating
            the child components.  It also allows to name the owned components with a unique name.
            Furthermore, functionality for sending notifications when a component is removed from the
            list or removed from memory alltogether is also introduced in TComponent

            TComponent  introduces  a  form  of  automatic  memory  management:  When  a  component  is
            destroyed, all its child components will be destroyed first.
            2.38.2         Method  overview

            __Page______Property_____________________________Description___________________________________________________________*
 *_______
              269       BeforeDestruction                    Overrides standard BeforeDestruction.
              269       Create                               Creates a new instance of the component.
              270       Destroy                              Destroys the instance of the component.
              270       DestroyComponents                    Destroy child components.
              270       Destroying                           Called when the component is being destroyed
              271       ExecuteAction                        Standard action execution method.
              271       FindComponent                        Finds and returns the named component in the owned
                                                             components.
              271       FreeNotification                     Ask  the  component  to  notify  called  when  it  is  being
                                                             destroyed.
              272       FreeOnRelease                        Part of the IVCLComObject interface.
              272       GetParentComponent                   Returns the parent component.
              272       HasParent                            Does the component have a parent ?
              272       InsertComponent                      Insert the given component in the list of owned compo-
                                                             nents.
              274       IsImplementorOf                      Checks if the current component is the implementor of
                                                             the interface
              274       ReferenceInterface                   Interface implementation of Notification
              273       RemoveComponent                      Remove  the  given  component  from  the  list  of  owned
                                                             components.
              271       RemoveFreeNotification               Remove a component from the Free Notification list.
              273       SafeCallException                    Part of the IVCLComObject Interface.
              273       SetSubComponent                      Sets the csSubComponent style.
              273       UpdateAction                         Updates the state of an action.
            __269_______WriteState___________________________Writes_the_component_to_a_stream._____________________________________*
 *_______


                                                                             268

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.3         Property  overview

                __Page______Property_____________________Access______Description___________________________________________________*
 *___________
                  274       ComponentCount               r           Count of owned components
                  275       ComponentIndex               rw          Index of component in it's owner's list.
                  274       Components                   r           Indexed list (zero-based) of all owned components.
                  275       ComponentState               r           Current component's state.
                  275       ComponentStyle               r           Current component's style.
                  276       DesignInfo                   rw          Information for IDE designer.
                  277       Name                         rws         Name of the component.
                  276       Owner                        r           Owner of this component.
                  277       Tag                          rw          Tag value of the component.
                __276_______VCLComObject_________________rw__________Not_implemented.______________________________________________*
 *___________
                2.38.4         TComponent.WriteState

    Synopsis:    Writes the component to a stream.

Declaration:     procedure  WriteState(Writer:  TWriter);    Virtual

    Visibility:   public

Description:     WriteState  writes  the  component's  current  state  to  a  stream  through  the  writer  (374  )
                object writer.  Values for all published properties of the component can be written to the
                stream.  Normally there is no need to call WriteState directly.  The streaming system calls
                WriteState itself.

                The  TComponent  (268  )  implementation  of  WriteState  simply  calls  TWriter.WriteData
                (374  ).  Descendent classes can, however, override WriteStateto provide additional processing
                of stream data.

    See also:    TComponent.ReadState (268  ), TStream.WriteComponent (337  ), TWriter.WriteData (374  )
                2.38.5         TComponent.Create

    Synopsis:    Creates a new instance of the component.

Declaration:     constructor  Create(AOwner:  TComponent);    Virtual

    Visibility:   public

Description:     Create  creates  a  new  instance  of  a  TComponent  class.   If  AOwner  is  not  Nil,  the  new
                component attempts to insert itself in the list of owned components of the owner.

    See also:    TComponent.Insert (268  ), TComponent.Owner (276  )
                2.38.6         TComponent.BeforeDestruction

    Synopsis:    Overrides standard BeforeDestruction.

Declaration:     procedure  BeforeDestruction;    Override

    Visibility:   public

Description:     BeforeDestruction is overridden by TComponent to set the csDestroying flag in Compo-
                nentState (185  )

    See also:    ComponentState (185  )



                                                                                 269

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.7         TComponent.Destroy

    Synopsis:    Destroys the instance of the component.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy sends a opRemove notification to all components in the free-notification list.  After
                that, all owned components are destroyed by calling DestroyComponents (270  ) (and hence
                removed from the list of owned components).  When this is done,  the component removes
                itself from its owner's child component list.  After that, the parent's destroy method is called.

    See also:    TComponent.Notification (268  ), TComponent.Owner (276  ), TComponent.DestroyComponents
                (270  ), TComponent.Components (274  )
                2.38.8         TComponent.DestroyComponents

    Synopsis:    Destroy child components.

Declaration:     procedure  DestroyComponents

    Visibility:   public

Description:     DestroyComponents calls the destructor of all owned components, till no more components
                are left in the Components (274  ) array.

                Calling  the  destructor  of  an  owned  component  has  as  the  effect  that  the  component  will
                remove  itself  from  the  list  of  owned  components,  if  nothing  has  disrupted  the  sequence  of
                destructors.

       Errors:   If an overridden 'destroy' method does not call it's intherited destructor or raises an excep-
                tion, it's TComponent.Destroy (270  ) destructor will not be called, which may result in an
                endless loop.

    See also:    TComponent.Destroy (270  ), TComponent.Components (274  )
                2.38.9         TComponent.Destroying

    Synopsis:    Called when the component is being destroyed

Declaration:     procedure  Destroying

    Visibility:   public

Description:     Destroying sets the csDestroying flag in the component's state (268  ) property, and does
                the same for all owned components.

                It is not necessary to call Destroying directly, the destructor Destroy (270  ) does this auto-
                matically.

    See also:    TComponent.State (268  ), TComponent.Destroy (270  )
                                                                                 270

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.10          TComponent.ExecuteAction

    Synopsis:    Standard action execution method.

Declaration:     function  ExecuteAction(Action:  TBasicAction)  :  Boolean;    Dynamic

    Visibility:   public

Description:     ExecuteAction  checks  whether  Action  handles  the  current  component,  and  if  yes,  calls
                the ExecuteAction method, passing itself as a parameter.  The function returns True if the
                action handles the current component.

    See also:    TBasicAction (237  ), TBasicAction.ExecuteAction (237  ), TBasicAction.HandlesTarget (238  ),
                UpdateAction (185  )
                2.38.11          TComponent.FindComponent

    Synopsis:    Finds and returns the named component in the owned components.

Declaration:     function  FindComponent(const  AName:  String)  :  TComponent

    Visibility:   public

Description:     FindComponent searches the component with name AName in the list of owned components.
                If  AName is empty, then Nil is returned.

    See also:    TComponent.Components (274  ), TComponent.Name (277  )
                2.38.12          TComponent.FreeNotification

    Synopsis:    Ask the component to notify called when it is being destroyed.

Declaration:     procedure  FreeNotification(AComponent:  TComponent)

    Visibility:   public

Description:     FreeNotification inserts AComponent in the freenotification list.  When the component is
                destroyed, the Notification (268  ) method is called for all components in the freenotification
                list.

    See also:    TComponent.Components (274  ), TComponent.Notification (268  )
                2.38.13          TComponent.RemoveFreeNotification

    Synopsis:    Remove a component from the Free Notification list.

Declaration:     procedure  RemoveFreeNotification(AComponent:  TComponent)

    Visibility:   public

Description:     RemoveFreeNotification removes AComponent from the freenotification list.

    See also:    FreeNotification (185  )
                                                                                 271

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.14          TComponent.FreeOnRelease

    Synopsis:    Part of the IVCLComObject interface.

Declaration:     procedure  FreeOnRelease

    Visibility:   public

Description:     Provided for Delphi compatibility, but is not yet impltmentedd.
                2.38.15          TComponent.GetParentComponent

    Synopsis:    Returns the parent component.

Declaration:     function  GetParentComponent  :  TComponent;    Dynamic

    Visibility:   public

Description:     GetParentComponent can be implemented to return the parent component of this compo-
                nent.  The implementation of this method in TComponent always returns Nil.  Descendent
                classes must override this method to return the visual parent of the component.

    See also:    TComponent.HasParent (272  ), TComponent.Owner (276  )
                2.38.16          TComponent.HasParent

    Synopsis:    Does the component have a parent ?

Declaration:     function  HasParent  :  Boolean;    Dynamic

    Visibility:   public

Description:     HasParent  can  be  implemented  to  return  whether  the  parent  of  the  component  exists.
                The  implementation  of  this  method  in  TComponent  always  returns  False,  and  should  be
                overridden by descendent classes to return True when a parent is available.  If  HasParent
                returns True, then GetParentComponent (272  ) will return the parent component.

    See also:    TComponent.HasParent (272  ), TComponent.Owner (276  )
                2.38.17          TComponent.InsertComponent

    Synopsis:    Insert the given component in the list of owned components.

Declaration:     procedure  InsertComponent(AComponent:  TComponent)

    Visibility:   public

Description:     InsertComponent  attempts  to  insert  AComponent  in  the  list  with  owned  components.  It
                first calls ValidateComponent (268  ) to see whether the component can be inserted.  It then
                checks whether there are no name conflicts by calling ValidateRename (268  ).  If neither of
                these checks have raised an exception the component is inserted, and notified of the insert.

    See also:    TComponent.RemoveComponent (273  ), TComponent.Insert (268  ), TComponent.ValidateContainer
                (268  ), TComponent.ValidateRename (268  ), TComponent.Notification (268  )


                                                                                 272

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.18          TComponent.RemoveComponent

    Synopsis:    Remove the given component from the list of owned components.

Declaration:     procedure  RemoveComponent(AComponent:  TComponent)

    Visibility:   public

Description:     RemoveComponent will send an opRemove notification to AComponent and will then proceed
                to remove AComponent from the list of owned components.

    See also:    TComponent.InsertComponent (272  ), TComponent.Remove (268  ), TComponent.ValidateRename
                (268  ), TComponent.Notification (268  )
                2.38.19          TComponent.SafeCallException

    Synopsis:    Part of the IVCLComObject Interface.

Declaration:     function  SafeCallException(ExceptObject:  TObject;ExceptAddr:  Pointer)
                                                             :  Integer;    Override

    Visibility:   public

Description:     Provided for Delphi compatibility, but not implemented.
                2.38.20          TComponent.SetSubComponent

    Synopsis:    Sets the csSubComponent style.

Declaration:     procedure  SetSubComponent(ASubComponent:  Boolean)

    Visibility:   public

Description:     SetSubComponent includes csSubComponent in the ComponentStyle (275  ) property if ASubComponent
                is True, and excludes it again if  ASubComponent is False.

    See also:    TComponent.ComponentStyle (275  )
                2.38.21          TComponent.UpdateAction

    Synopsis:    Updates the state of an action.

Declaration:     function  UpdateAction(Action:  TBasicAction)  :  Boolean;    Dynamic

    Visibility:   public

Description:     UpdateAction checks whether Action handles the current component, and if yes, calls the
                UpdateTarget method, passing itself as a parameter.  The function returns True if the action
                handles the current component.

    See also:    TBasicAction (237  ), TBasicAction.UpdateTarget (239  ), TBasicAction.HandlesTarget (238  ),
                ExecuteAction (185  )


                                                                                 273

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.22          TComponent.IsImplementorOf

    Synopsis:    Checks if the current component is the implementor of the interface

Declaration:     function  IsImplementorOf(const  Intf:  IInterface)  :  Boolean

    Visibility:   public

Description:     IsImplementorOf  returns  True  if  the  current  component  implements  the  given  interface.
                The interface should descend from IInterfaceComponentReference (218  ) and the GetComponent
                method should return the current instance.

    See also:    IInterfaceComponentReference (218  )
                2.38.23          TComponent.ReferenceInterface

    Synopsis:    Interface implementation of Notification

Declaration:     procedure  ReferenceInterface(const  intf:  IInterface;op:  TOperation)

    Visibility:   public

Description:     ReferenceInterface  can  be  used  to  notify  an  interface  of  a  component  operation:  it  is
                the equivalent of the TComponent.Notification (268  ) method of  TComponent for interfaces.
                If the interface implements IInterfaceComponentReference (218  ), then the component that
                implements it is notified of the given operation Op.

       Errors:   None.

    See also:    TComponent.Notification (268  ), IInterfaceComponentReference (218  )
                2.38.24          TComponent.Components

    Synopsis:    Indexed list (zero-based) of all owned components.

Declaration:     Property  Components[Index:  Integer]:  TComponent

    Visibility:   public

      Access:    Read

Description:     Components provides indexed access to the list of owned components.  Index can range from
                0 to ComponentCount-1 (274  ).

    See also:    TComponent.ComponentCount (274  ), TComponent.Owner (276  )
                2.38.25          TComponent.ComponentCount

    Synopsis:    Count of owned components

Declaration:     Property  ComponentCount  :  Integer

    Visibility:   public

      Access:    Read

Description:     ComponentCount returns the number of components that the current component owns.  It
                can be used to determine the valid index range in the Component (274  ) array.

    See also:    TComponent.Components (274  ), TComponent.Owner (276  )



                                                                                 274

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.26          TComponent.ComponentIndex

    Synopsis:    Index of component in it's owner's list.

Declaration:     Property  ComponentIndex  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     ComponentIndex is the index of the current component in its owner's list of components.  If
                the component has no owner, the value of this property is -1.

    See also:    TComponent.Components (274  ), TComponent.ComponentCount (274  ), TComponent.Owner
                (276  )
                2.38.27          TComponent.ComponentState

    Synopsis:    Current component's state.

Declaration:     Property  ComponentState  :  TComponentState

    Visibility:   public

      Access:    Read

Description:     ComponentState  indicates  the  current  state  of  the  component.  It  is  a  set  of  flags  which
                indicate the various stages in the lifetime of a component.  The following values can occur in
                this set:



                                                          Table 2.17:  Component states


                         __Flag________________________Meaning_____________________________________________________________________*
 *__
                           csLoading                   The component is being loaded from stream
                           csReading                   Component properties are being read from stream.
                           csWriting                   Component properties are weing written to stream.
                           csDestroying                The component or one of it's owners is being destoyed.
                           csAncestor                  The component is being streamed as part of a frame
                           csUpdating                  The component is being updated
                           csFixups                    References to other components are being resolved
                           csFreeNotification          The component has freenotifications.
                           csInline                    The component is being loaded as part of a frame
                           csDesignInstance            ?  not used.
                The component state is set by various actions such as reading it from stream, destroying it
                etc.

    See also:    TComponent.SetAncestor  (268  ),  TComponent.SetDesigning  (268  ),  TComponent.SetInline
                (268  ), TComponent.SetDesignInstance (268  ), TComponent.Updating (268  ), TComponent.Updated
                (268  ), TComponent.Loaded (268  )
                2.38.28          TComponent.ComponentStyle

    Synopsis:    Current component's style.

Declaration:     Property  ComponentStyle  :  TComponentStyle



                                                                                 275

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    Visibility:  public

      Access:    Read

Description:     Current component's style.
                2.38.29          TComponent.DesignInfo

    Synopsis:    Information for IDE designer.

Declaration:     Property  DesignInfo  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     DesignInformation can be used by an IDE to store design information in the component.
                It should not be used by an application programmer.

    See also:    TComponent.Tag (277  )
                2.38.30          TComponent.Owner

    Synopsis:    Owner of this component.

Declaration:     Property  Owner  :  TComponent

    Visibility:   public

      Access:    Read

Description:     Owner returns the owner of this component.  The owner cannot be set except by explicitly
                inserting  the  component  in  another  component's  owned  components  list  using  that  com-
                ponent's InsertComponent (272  ) method, or by removing the component from it's owner's
                owned component list using the RemoveComponent (273  ) method.

    See also:    TComponent.Components (274  ), TComponent.InsertComponent (272  ), TComponent.RemoveComponent
                (273  )
                2.38.31          TComponent.VCLComObject

    Synopsis:    Not implemented.

Declaration:     Property  VCLComObject  :  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     VCLComObject is not yet implemented in Free Pascal.

                                                                                 276

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.38.32          TComponent.Name

    Synopsis:    Name of the component.

Declaration:     Property  Name  :  TComponentName

    Visibility:   published

      Access:    Read,Write

Description:     Name  is  the  name  of  the  component.   This  name  should  be  a  valid  identifier,  i.e.   must
                start  with  a  letter,  and  can  contain  only  letters,  numbers  and  the  underscore  character.
                When  attempting  to  set  the  name  of  a  component,  the  name  will  be  checked  for  validity.
                Furthermore, when a component is owned by another component, the name must be either
                empty or must be unique among the child component names.

       Errors:   Attempting to set the name to an invalid value will result in an exception being raised.

    See also:    TComponent.ValidateRename (268  ), TComponent.Owner (276  )
                2.38.33          TComponent.Tag

    Synopsis:    Tag value of the component.

Declaration:     Property  Tag  :  LongInt

    Visibility:   published

      Access:    Read,Write

Description:     Tag  can  be  used  to  store  an  integer  value  in  the  component.  This  value  is  streamed  to-
                gether with all other published properties.  It can be used for instance to quickly identify a
                component in an event handler.

    See also:    TComponent.Name (277  )
                2.39          TCustomMemoryStream



                2.39.1         Description

                TCustomMemoryStream is the parent class for streams that stored their data in memory.  It
                introduces all needed functions to handle reading from and navigating through the memory,
                and introduces a Memory (279  ) property which points to the memory area where the stream
                data is kept.

                The  only  thing  which  TCustomMemoryStream  does  not  do  is  obtain  memory  to  store  data
                when writing data or the writing of data.  This functionality is implemented in descendent
                streams such as TMemoryStream (307  ).  The reason for this approach is that this way it is
                possible to create e.g.  read-only descendents of TCustomMemoryStream that point to a fixed
                part in memory which can be read from, but not written to.

 Remark:         Since TCustomMemoryStream is an abstract class, do not create instances of TMemoryStream
                directly.  Instead, create instances of descendents such as TMemoryStream (307  ).
                                                                                 277

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.39.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  278       GetSize                 return the size of the stream.
                  278       Read                    Reads Count bytes from the stream into buffer.
                  279       SaveToFile              Writes the contents of the stream to a file.
                  279       SaveToStream            Writes the contents of the memory stream to another stream.
                __278_______Seek____________________Sets_a_new_position_in_the_stream._____________________________________________*
 *___________
                2.39.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __279_______Memory__________r____________Pointer_to_the_data_kept_in_the_memory_stream.____________________________*
 *___________
                2.39.4         TCustomMemoryStream.GetSize

    Synopsis:    return the size of the stream.

Declaration:     function  GetSize  :  Int64;    Override

    Visibility:   public

Description:     GetSize returns the size of the reseved memory.  It should not be used directly.

    See also:    TStream.Size (342  )
                2.39.5         TCustomMemoryStream.Read

    Synopsis:    Reads Count bytes from the stream into buffer.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read reads Count bytes from the stream into the memory pointed to by buffer.  It returns
                the number of bytes actually read.

                This method overrides the TStream.Read (334  ) method of TStream (333  ).  It will read as
                much bytes as are still available in the memory area pointer to by Memory (279  ).  After the
                bytes are read, the internal stream position is updated.

    See also:    TCustomMemoryStream.Memory (279  ), TStream.Read (334  )
                2.39.6         TCustomMemoryStream.Seek

    Synopsis:    Sets a new position in the stream.

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek  overrides  the  abstract  TStream.Seek  (335  )  method.   It  simply  updates  the  internal
                stream position, and returns the new position.

       Errors:   No  checking  is  done  whether  the  new  position  is  still  a  valid  position,  i.e.   whether  the
                position  is  still  within  the  range  0..Size.   Attempting  a  seek  outside  the  valid  memory
                range of the stream may result in an exception at the next read or write operation.

    See also:    TStream.Position (342  ), TStream.Size (342  ), TCustomMemoryStream.Memory (279  )



                                                                                 278

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.39.7         TCustomMemoryStream.SaveToStream

    Synopsis:    Writes the contents of the memory stream to another stream.

Declaration:     procedure  SaveToStream(Stream:  TStream)

    Visibility:   public

Description:     SaveToStream writes the contents of the memory stream to Stream.  The content of Stream
                is not cleared first.  The current position of the memory stream is not changed by this action.

 Remark:         This method will work much faster than the use of the TStream.CopyFrom (336  ) method:


                Seek(0,soFromBeginning);
                    Stream.CopyFrom(Self,Size);


                because the CopyFrom method copies the contents in blocks, while SaveToStream writes the
                contents of the memory as one big block.

       Errors:   If an error occurs when writing to Stream an EStreamError (216  ) exception will be raised.

    See also:    TCustomMemoryStream.SaveToFile (279  ), TStream.CopyFrom (336  )
                2.39.8         TCustomMemoryStream.SaveToFile

    Synopsis:    Writes the contents of the stream to a file.

Declaration:     procedure  SaveToFile(const  FileName:  String)

    Visibility:   public

Description:     SaveToFile  writes  the  contents  of  the  stream  to  a  file  with  name  FileName.   It  simply
                creates a filestream and writes the contents of the memorystream to this file stream using
                TCustomMemoryStream.SaveToStream (279  ).

 Remark:         This method will work much faster than the use of the TStream.CopyFrom (336  ) method:


                Stream:=TFileStream.Create(fmCreate,FileName);
                    Seek(0,soFromBeginning);
                    Stream.CopyFrom(Self,Size);


                because  the  CopyFrom  method  copies  the  contents  in  blocks,  while  SaveToFile  writes  the
                contents of the memory as one big block.

       Errors:   If  an  error  occurs  when  creating  or  writing  to  the  file,  an  EStreamError  (216  )  exception
                may occur.

    See also:    TCustomMemoryStream.SaveToStream (279  ), TFileStream (285  ), TStream.CopyFrom (336  )
                2.39.9         TCustomMemoryStream.Memory

    Synopsis:    Pointer to the data kept in the memory stream.

Declaration:     Property  Memory  :  Pointer

    Visibility:   public

      Access:    Read
                                                                                 279

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     Memory points to the memory area where stream keeps it's data.  The property is read-only,
                so the pointer cannot be set this way.

 Remark:         Do  not  write  to  the  memory  pointed  to  by  Memory,  since  the  memory  content  may  be
                read-only, and thus writing to it may cause errors.

    See also:    TStream.Size (342  )
                2.40          TDataModule



                2.40.1         Description

                TDataModule is a container for non-visual objects which can be used in an IDE to group non-
                visual objects which can be used by various other containers (forms) in a project.  Notably,
                data access components are typically stored on a datamodule.  Web components and services
                can also be implemented as descendents of datamodules.

                TDataModule  introduces  some  events  which  make  it  easier  to  program,  and  provides  the
                needed streaming capabilities for persistent storage.

                An IDE will typically allow to create a descendent of TDataModule which contains non-visual
                components in it's published property list.
                2.40.2         Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  281       AfterConstruction            Overrides standard TObject (185  ) behaviour.
                  281       BeforeDestruction
                  280       Create                       Create a new instance of a TDataModule.
                  281       CreateNew
                __281_______Destroy______________________Destroys_the_TDataModule_instance.________________________________________*
 *___________
                2.40.3         Property  overview

                __Page______Property__________________Access_______Description_____________________________________________________*
 *___________
                  282       DesignOffset              rw           Position property needed for manipulation in an IDE.
                  282       DesignSize                rw           Size property needed for manipulation in an IDE.
                  283       OldCreateOrder            rw           Determines when OnCreate and OnDestroy are trig-
                                                                   gered.
                  282       OnCreate                  rw           Event handler, called when the datamodule is created.
                  283       OnDestroy                 rw           Event  handler,  called  when  the  datamodule  is  de-
                ___________________________________________________stroyed.________________________________________________________*
 *___________
                2.40.4         TDataModule.Create

    Synopsis:    Create a new instance of a TDataModule.

Declaration:     constructor  Create(AOwner:  TComponent);    Override

    Visibility:   public

Description:     Create creates a new instance of the TDatamodule and calls TDatamodule.CreateNew (281  ).
                After  that  it  reads  the  published  properties  from  a  stream  using  InitInheritedComponent
                (206  ) if a descendent class is instantiated.  If the OldCreateOrder (283  ) property is True, the
                OnCreate (185  ) event is called.



                                                                                 280

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
       Errors:   An exception can be raised during the streaming operation.

    See also:    TDataModule.CreateNew (281  )
                2.40.5         TDataModule.CreateNew

    Synopsis:

Declaration:     constructor  CreateNew(AOwner:  TComponent)
                constructor  CreateNew(AOwner:  TComponent;CreateMode:  Integer);    Virtual

    Visibility:   public

Description:     CreateNew creates a new instance of the class, but bypasses the streaming mechanism.  The
                CreateMode parameter (by default zero) is not used in TDataModule.  If the AddDataModule
                (199  ) handler is set, then it is called, with the newly created instance as an argument.

    See also:    TDataModule.Create (280  ), AddDataModule (199  ), TDataModule.OnCreate (282  )
                2.40.6         TDataModule.Destroy

    Synopsis:    Destroys the TDataModule instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy destroys the TDataModule instance.  If the OldCreateOrder (283  ) property is True
                the OnDestroy (283  ) event handler is called prior to destroying the data module.

                Before calling the inherited destroy, the RemoveDataModule (199  ) handler is called if it is
                set, and Self is passed as a parameter.

       Errors:   An event can be raised during the OnDestroy event handler.

    See also:    TDataModule.OnDestroy (283  ), RemoveDataModule (199  )
                2.40.7         TDataModule.AfterConstruction

    Synopsis:    Overrides standard TObject (185  ) behaviour.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction calls the OnCreate (282  ) handler if the OldCreateOrder (283  ) property
                is False.

    See also:    TDataModule.OldCreateOrder (283  ), TDataModule.OnCreate (282  )
                2.40.8         TDataModule.BeforeDestruction

    Synopsis:

Declaration:     procedure  BeforeDestruction;    Override

    Visibility:   public

                                                                                 281

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     BeforeDestruction calls the OnDestroy (282  ) handler if the OldCreateOrder (283  ) prop-
                erty is False.

    See also:    TDataModule.OldCreateOrder (283  ), TDataModule.OnDestroy (283  )
                2.40.9         TDataModule.DesignOffset

    Synopsis:    Position property needed for manipulation in an IDE.

Declaration:     Property  DesignOffset  :  TPoint

    Visibility:   public

      Access:    Read,Write

Description:     DesignOffset is the position of the datamodule when displayed in an IDE. It is streamed
                to the form file, and should not be used at run-time.

    See also:    TDataModule.DesignSize (282  )
                2.40.10          TDataModule.DesignSize

    Synopsis:    Size property needed for manipulation in an IDE.

Declaration:     Property  DesignSize  :  TPoint

    Visibility:   public

      Access:    Read,Write

Description:     DesignSize is the size of the datamodule when displayed in an IDE. It is streamed to the
                form file, and should not be used at run-time.

    See also:    TDataModule.DesignOffset (282  )
                2.40.11          TDataModule.OnCreate

    Synopsis:    Event handler, called when the datamodule is created.

Declaration:     Property  OnCreate  :  TNotifyEvent

    Visibility:   published

      Access:    Read,Write

Description:     The OnCreate event is triggered when the datamodule is created and streamed.  The exact
                moment of triggering is dependent on the value of the OldCreateOrder (283  ) property.

    See also:    TDataModule.Create (280  ), TDataModule.CreateNew (281  ), TDataModule.OldCreateOrder
                (283  )

                                                                                 282

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.40.12          TDataModule.OnDestroy

    Synopsis:    Event handler, called when the datamodule is destroyed.

Declaration:     Property  OnDestroy  :  TNotifyEvent

    Visibility:   published

      Access:    Read,Write

Description:     The OnDestroy event is triggered when the datamodule is destroyed The exact moment of
                triggering is dependent on the value of the OldCreateOrder (283  ) property.

    See also:    TDataModule.Destroy  (281  ),  TDataModule.OnCreate  (282  ),  TDataModule.Create  (280  ),
                TDataModule.CreateNew (281  ), TDataModule.OldCreateOrder (283  )
                2.40.13          TDataModule.OldCreateOrder

    Synopsis:    Determines when OnCreate and OnDestroy are triggered.

Declaration:     Property  OldCreateOrder  :  Boolean

    Visibility:   published

      Access:    Read,Write

Description:     OldCreateOrder determines when exactly the OnCreate (282  ) and OnDestroy (283  ) event
                handlers are called:

    See also:    TDataModule.OnDestroy (283  ), TDataModule.OnCreate (282  ), TDataModule.Destroy (281  ),
                TDataModule.Create (280  ), TDataModule.CreateNew (281  ), TDataModule.OldCreateOrder
                (283  )
                2.41          TFiler



                2.41.1         Description

                Class responsible for streaming of components.
                2.41.2         Method  overview

                __Page______Property__________________________Description__________________________________________________________*
 *___________
                  284       DefineBinaryProperty
                __284_______DefineProperty_________________________________________________________________________________________*
 *___________
                2.41.3         Property  overview

                __Page______Property_________________Access_______Description______________________________________________________*
 *___________
                  285       Ancestor                 rw           Ancestor component from which an inherited compo-
                                                                  nent is streamed.
                  285       IgnoreChildren           rw           Determines whether children will be streamed as well.
                  284       LookupRoot               r            Component used to look up ancestor components.
                  284       Root                     rw           The root component is the initial component which is
                __________________________________________________being_streamed.__________________________________________________*
 *___________


                                                                                 283

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.41.4         TFiler.DefineProperty

    Synopsis:

Declaration:     procedure  DefineProperty(const  Name:  String;ReadData:  TReaderProc;
                                                        WriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Virtual;    Abstract

    Visibility:   public

Description:
                2.41.5         TFiler.DefineBinaryProperty

    Synopsis:

Declaration:     procedure  DefineBinaryProperty(const  Name:  String;ReadData:  TStreamProc;
                                                                  WriteData:  TStreamProc;HasData:  Boolean)
                                                                  ;    Virtual;    Abstract

    Visibility:   public

Description:
                2.41.6         TFiler.Root

    Synopsis:    The root component is the initial component which is being streamed.

Declaration:     Property  Root  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     The streaming process will stream a component and all the components which it owns.  The
                Root component is the component which is initially streamed.

    See also:    TFiler.LookupRoot (284  )
                2.41.7         TFiler.LookupRoot

    Synopsis:    Component used to look up ancestor components.

Declaration:     Property  LookupRoot  :  TComponent

    Visibility:   public

      Access:    Read

Description:     When comparing inherited component's values against parent values, the values are com-
                pared with the component in LookupRoot.  Initially, it is set to Root (284  ).

    See also:    TFiler.Root (284  )
                                                                                 284

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.41.8         TFiler.Ancestor

    Synopsis:    Ancestor component from which an inherited component is streamed.

Declaration:     Property  Ancestor  :  TPersistent

    Visibility:   public

      Access:    Read,Write

Description:     When  streaming  a  component,  this  is  the  parent  component.  Only  properties  that  differ
                from the parent's property value will be streamed.

    See also:    TFiler.Root (284  ), TFiler.LookupRoot (284  )
                2.41.9         TFiler.IgnoreChildren

    Synopsis:    Determines whether children will be streamed as well.

Declaration:     Property  IgnoreChildren  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     By default, all children (i.e.  owned objects) will also be streamed when streaming a com-
                ponent.  This property can be used to prevent owned objects from being streamed.
                2.42          TFileStream



                2.42.1         Description

                TFileStream is a TStream (333  ) descdendent that stores or reads it's data from a named
                file in the filesystem of the operating system.

                To this end, it overrides some of the methods in TStream and implements them for the case
                of files on disk, and it adds the FileName (286  ) property to the list of public properties.
                2.42.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  285       Create          Creates a file stream.
                __286_______Destroy_________Destroys_the_file_stream.______________________________________________________________*
 *___________
                2.42.3         Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __286_______FileName_________r____________The_filename_of_the_stream.______________________________________________*
 *___________
                2.42.4         TFileStream.Create

    Synopsis:    Creates a file stream.

Declaration:     constructor  Create(const  AFileName:  String;Mode:  Word)
                constructor  Create(const  AFileName:  String;Mode:  Word;Rights:  Cardinal)

                                                                                 285

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    Visibility:  public

Description:     Create  creates  a  new  instance  of  a  TFileStream  class.  It  opens  the  file  AFileName  with
                mode Mode, which can have one of the following values:



                                                                       Table 2.18:

                      fmCreate                      TFileStream.Create (285  ) creates a new file if needed.
                      fmOpenRead                    TFileStream.Create (285  ) opens a file with read-only access.
                      fmOpenWrite                   TFileStream.Create (285  ) opens a file with write-only access.
                      fmOpenReadWrite               TFileStream.Create (285  ) opens a file with read-write access.
                After the file has been opened in the requested mode and a handle has been obtained from
                the operating system, the inherited constructor is called.

       Errors:   If the file could not be opened in the requested mode, an EFOpenError (215  ) exception is
                raised.

    See also:    TStream (333  ), TFileStream.FileName (286  ), THandleStream.Create (294  )
                2.42.5         TFileStream.Destroy

    Synopsis:    Destroys the file stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy closes the file (causing possible buffered data to be written to disk) and then calls
                the inherited destructor.

                Do not call destroy directly, instead call the Free method.  Destroy does not check whether
                Self is nil, while Free does.

    See also:    TFileStream.Create (285  )
                2.42.6         TFileStream.FileName

    Synopsis:    The filename of the stream.

Declaration:     Property  FileName  :  String

    Visibility:   public

      Access:    Read

Description:     FileName is the name of the file that the stream reads from or writes to.  It is the name as
                passed in the constructor of the stream; it cannot be changed.  To write to another file, the
                stream must be freed and created again with the new filename.

    See also:    TFileStream.Create (285  )

                                                                                 286

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.43          TFPList



                2.43.1         Description

                TFPList is a class that can be used to manage collections of pointers.  It introduces methods
                and properties to store the pointers, search in the list of pointers, sort them.  It manages its
                memory by itself, no intervention for that is needed.  Contrary to TList (301  ), TFPList has
                no notification mechanism.  If no notification mechanism is used, it is better to use TFPList
                instead of  TList, as the performance of  TFPList is much higher.

                To  manage  collections  of  strings,  it  is  better  to  use  a  TStrings  (351  )  descendent  such  as
                TStringList (347  ).  To manage general objects, a TCollection (260  ) class exists, from which
                a descendent can be made to manage collections of various kinds.
                2.43.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  288       Add                  Adds a new pointer to the list.
                  288       AddList              Add all pointers from another list
                  291       Assign               Assigns all items of a list to this list.
                  288       Clear                Clears the pointer list.
                  288       Delete               Removes a pointer from the list.
                  287       Destroy              Destroys  the  list  and  releases  the  memory  used  to  store  the  list
                                                 elements.
                  289       Error                Raises an EListError (215  ) exception.
                  289       Exchange             Exchanges two pointers in the list.
                  289       Expand               Increases the capacity of the list if needed.
                  289       Extract              Remove the first occurrence of a pointer from the list.
                  290       First                Returns the first non-nil pointer in the list.
                  292       ForEachCall          Call a procedure or method for each pointer in the list.
                  290       IndexOf              Returns the index of a given pointer.
                  290       Insert               Inserts a new pointer in the list at a given position.
                  290       Last                 Returns the last non-nil pointer in the list.
                  291       Move                 Moves a pointer from one position in the list to another.
                  291       Pack                 Removes Nil pointers from the list and frees unused memory.
                  291       Remove               Removes a value from the list.
                __292_______Sort_________________Sorts_the_pointers_in_the_list.___________________________________________________*
 *___________
                2.43.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  292       Capacity        rw           Current capacity (i.e.  number of pointers that can be stored)
                                                         of the list.
                  293       Count           rw           Current number of pointers in the list.
                  293       Items           rw           Provides access to the pointers in the list.
                __293_______List____________r____________Memory_array_where_pointers_are_stored.___________________________________*
 *___________
                2.43.4         TFPList.Destroy

    Synopsis:    Destroys the list and releases the memory used to store the list elements.

Declaration:     destructor  Destroy;    Override

    Visibility:   public
                                                                                 287

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     Destroy  destroys  the  list  and  releases  the  memory  used  to  store  the  list  elements.   The
                elements themselves are in no way touched, i.e.  any meomory they point to must be explicitly
                released before calling the destructor.
                2.43.5         TFPList.AddList

    Synopsis:    Add all pointers from another list

Declaration:     procedure  AddList(AList:  TFPList)

    Visibility:   public

Description:     AddList adds all pointers from AList to the list.  If a pointer is already present, it is added
                a second time.

    See also:    TFPList.Assign (291  ), TList.AddList (302  )
                2.43.6         TFPList.Add

    Synopsis:    Adds a new pointer to the list.

Declaration:     function  Add(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Add  adds  a  new  pointer  to  the  list  after  the  last  pointer  (i.e.   at  position  Count,  thus
                increasing  the  item  count  with  1.  If  the  list  is  at  full  capacity,  the  capacity  of  the  list  is
                expanded, using the Grow (287  ) method.

                To insert a pointer at a certain position in the list, use the Insert (290  ) method instead.

    See also:    TFPList.Delete (288  ), TFPList.Grow (287  ), TFPList.Insert (290  )
                2.43.7         TFPList.Clear

    Synopsis:    Clears the pointer list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear removes all pointers from the list, and sets the capacity to 0, thus freeing any memory
                allocated to maintain the list.

    See also:    TFPList.Destroy (287  )
                2.43.8         TFPList.Delete

    Synopsis:    Removes a pointer from the list.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete removes the pointer at position Index from the list, shifting all following pointers
                one position up (or to the left).

                The memory the pointer is pointing to is not  deallocated.
                                                                                 288

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.43.9         TFPList.Error

    Synopsis:    Raises an EListError (215  ) exception.

Declaration:     procedure  Error(const  Msg:  String;Data:  PtrInt)

    Visibility:   public

Description:     Error raises an EListError (215  ) exception, with a message formatted with Msg and Data.
                2.43.10          TFPList.Exchange

    Synopsis:    Exchanges two pointers in the list.

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer)

    Visibility:   public

Description:     Exchange exchanges the pointers at positions Index1 and Index2.  Both pointers must be
                withing the current range of the list, or an EListError (215  ) exception will be raised.
                2.43.11          TFPList.Expand

    Synopsis:    Increases the capacity of the list if needed.

Declaration:     function  Expand  :  TFPList

    Visibility:   public

Description:     Expand increases the capacity of the list if the current element count matches the current
                list capacity.

                The capacity is increased according to the following algorithm:


                     1.If the capacity is less than 3, the capacity is increased with 4.

                     2.If the capacity is larger than 3 and less than 8, the capacity is increased with 8.

                     3.If the capacity is larger than 8, the capacity is increased with 16.


                The return value is Self.

    See also:    TFPList.Capacity (292  )
                2.43.12          TFPList.Extract

    Synopsis:    Remove the first occurrence of a pointer from the list.

Declaration:     function  Extract(Item:  Pointer)  :  Pointer

    Visibility:   public

Description:     Extract searches for the first occurrence of  Item in the list and deletes it from the list.  If
                Item was found, it's value is returned.  If  Item was not found, Nil is returned.

    See also:    TFPList.Delete (288  )


                                                                                 289

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.43.13          TFPList.First

    Synopsis:    Returns the first non-nil pointer in the list.

Declaration:     function  First  :  Pointer

    Visibility:   public

Description:     First returns the value of the first non-nil pointer in the list.

                If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

    See also:    TFPList.Last (290  )
                2.43.14          TFPList.IndexOf

    Synopsis:    Returns the index of a given pointer.

Declaration:     function  IndexOf(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOf searches for the pointer Item in the list of pointers, and returns the index of the
                pointer, if found.

                If no pointer with the value Item was found, -1 is returned.
                2.43.15          TFPList.Insert

    Synopsis:    Inserts a new pointer in the list at a given position.

Declaration:     procedure  Insert(Index:  Integer;Item:  Pointer)

    Visibility:   public

Description:     Insert inserts pointer Item at position Index in the list.  All pointers starting from Index
                are shifted to the right.

                If  Index is not a valid position, then a EListError (215  ) exception is raised.

    See also:    TFPList.Add (288  ), TFPList.Delete (288  )
                2.43.16          TFPList.Last

    Synopsis:    Returns the last non-nil pointer in the list.

Declaration:     function  Last  :  Pointer

    Visibility:   public

Description:     Last returns the value of the last non-nil pointer in the list.

                If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

    See also:    TFPList.First (290  )

                                                                                 290

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.43.17          TFPList.Move

    Synopsis:    Moves a pointer from one position in the list to another.

Declaration:     procedure  Move(CurIndex:  Integer;NewIndex:  Integer)

    Visibility:   public

Description:     Move moves the pointer at position CurIndex to position NewIndex.  This is done by storing
                the value at position CurIndex, deleting the pointer at position CurIndex, and reinserting
                the value at position NewIndex

                If  CurIndex  or  Newindex  are  not  inside  the  valid  range  of  indices,  an  EListError  (215  )
                exception is raised.

    See also:    TFPList.Exchange (289  )
                2.43.18          TFPList.Assign

    Synopsis:    Assigns all items of a list to this list.

Declaration:     procedure  Assign(ListA:  TFPList;AOperator:  TListAssignOp;ListB:  TFPList)

    Visibility:   public

Description:     Assign clears the list and adds all pointers in Obj to the list.

    See also:    TFPList.Add (288  ), TFPList.Clear (288  )
                2.43.19          TFPList.Remove

    Synopsis:    Removes a value from the list.

Declaration:     function  Remove(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Remove searches Item in the list, and, if it finds it, deletes the item from the list.  Only the
                first occurrence of  Item is removed.

    See also:    TFPList.Delete (288  ), TFPList.IndexOf (290  ), TFPList.Insert (290  )
                2.43.20          TFPList.Pack

    Synopsis:    Removes Nil pointers from the list and frees unused memory.

Declaration:     procedure  Pack

    Visibility:   public

Description:     Pack  removes  all  nil  pointers  from  the  list.   The  capacity  of  the  list  is  then  set  to  the
                number of pointers in the list.  This method can be used to free unused memory if the list
                has grown to very large sizes and has a lot of unneeded nil pointers in it.

    See also:    TFPList.Clear (288  )


                                                                                 291

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.43.21          TFPList.Sort

    Synopsis:    Sorts the pointers in the list.

Declaration:     procedure  Sort(Compare:  TListSortCompare)

    Visibility:   public

Description:     Sort>  sorts  the  pointers  in  the  list.  Two  pointers  are  compared  by  passing  them  to  the
                Compare function.  The result of this function determines how the pointers will be sorted:


                      oIf the result of this function is negative,  the first pointer is assumed to be 'less' than
                       the second and will be moved before the second in the list.

                      oIf the function result is positive,  the first pointer is assumed to be 'greater than' the
                       second and will be moved after the second in the list.

                      oif the function result is zero, the pointers are assumed to be 'equal' and no moving will
                       take place.


                The sort is done using a quicksort algorithm.
                2.43.22          TFPList.ForEachCall

    Synopsis:    Call a procedure or method for each pointer in the list.

Declaration:     procedure  ForEachCall(proc2call:  TListCallback;arg:  pointer)
                procedure  ForEachCall(proc2call:  TListStaticCallback;arg:  pointer)

    Visibility:   public

Description:     ForEachCall iterates over all pointers in the list and calls proc2call, passing it the pointer
                and the additional arg data pointer.  Proc2Call can be a method or a static procedure.

       Errors:   None.

    See also:    TListStaticCallback (193  ), TListCallback (193  )
                2.43.23          TFPList.Capacity

    Synopsis:    Current capacity (i.e.  number of pointers that can be stored) of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity contains the number of pointers the list can store before it starts to grow.

                If a new pointer is added to the list using add (288  ) or insert (290  ), and there is not enough
                memory to store the new pointer, then the list will try to allocate more memory to store the
                new pointer.  Since this is a time consuming operation, it is important that this operation be
                performed as little as possible.  If it is known how many pointers there will be before filling
                the list,  it is a good idea to set the capacity first before filling.  This ensures that the list
                doesn't need to grow, and will speed up filling the list.

    See also:    TFPList.SetCapacity (287  ), TFPList.Count (293  )



                                                                                 292

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.43.24          TFPList.Count

    Synopsis:    Current number of pointers in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current number of (possibly Nil) pointers in the list.  Since the list is zero-based,
                the index of the largest pointer is Count-1.
                2.43.25          TFPList.Items

    Synopsis:    Provides access to the pointers in the list.

Declaration:     Property  Items[Index:  Integer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items is used to access the pointers in the list.  It is the default property of the TFPList
                class, so it can be omitted.

                The list is zero-based, so Index must be in the range 0 to Count-1.
                2.43.26          TFPList.List

    Synopsis:    Memory array where pointers are stored.

Declaration:     Property  List  :  PPointerList

    Visibility:   public

      Access:    Read

Description:     List points to the memory space where the pointers are stored.  This can be used to quickly
                copy the list of pinters to another location.
                2.44          THandleStream



                2.44.1         Description

                THandleStream  is  an  abstract  descendent  of  the  TStream  (333  )  class  that  provides  meth-
                ods for a stream to handle all reading and writing to and from a handle,  provided by the
                underlying OS. To this end, it overrides the Read (294  ) and Write (294  ) methods of TStream.

 Remark:


                     o  ThandleStream does not obtain a handle from the OS by itself, it just handles reading
                        and  writing  to  such  a  handle  by  wrapping  the  system  calls  for  reading  and  writing;
                        Descendent classes should obtain a handle from the OS by themselves and pass it on
                        in the inherited constructor.

                     o  Contrary to Delphi, no seek is implemented for THandleStream, since pipes and sockets
                        do not support this.  The seek is implemented in descendent methods that support it.
                                                                                 293

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.44.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  294       Create          Create a handlestream from an OS Handle.
                  294       Read            Overrides standard read method.
                  295       Seek            Overrides the Seek method.
                __294_______Write___________Overrides_standard_write_method._______________________________________________________*
 *___________
                2.44.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __295_______Handle__________r____________The_OS_handle_of_the_stream.______________________________________________*
 *___________
                2.44.4         THandleStream.Create

    Synopsis:    Create a handlestream from an OS Handle.

Declaration:     constructor  Create(AHandle:  Integer)

    Visibility:   public

Description:     Create creates a new instance of a THandleStream class.  It stores AHandle in an internal
                variable and then calls the inherited constructor.

    See also:    TStream (333  )
                2.44.5         THandleStream.Read

    Synopsis:    Overrides standard read method.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the Read (334  ) method of  TStream.  It uses the Handle (295  ) property to
                read the Count bytes into Buffer

                If no error occurs while reading, the number of bytes actually read will be returned.

       Errors:   If the operating system reports an error while reading from the handle, -1 is returned.

    See also:    TStream.Read (334  ), THandleStream.Write (294  ), THandleStream.Handle (295  )
                2.44.6         THandleStream.Write

    Synopsis:    Overrides standard write method.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overrides the Write (335  ) method of  TStream.  It uses the Handle (295  ) property to
                write the Count bytes from Buffer.

                If no error occurs while writing, the number of bytes actually written will be returned.

       Errors:   If the operating system reports an error while writing to the handle, 0 is returned.

    See also:    TStream.Read (334  ), THandleStream.Write (294  ), THandleStream.Handle (295  )



                                                                                 294

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.44.7         THandleStream.Seek

    Synopsis:    Overrides the Seek method.

Declaration:     function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64
                                      ;    Override

    Visibility:   public

Description:     seek uses the FileSeek (1424   ) method to position the stream on the desired position.  Note
                that handle stream descendents (notably pipes) can override the method to prevent the seek.
                2.44.8         THandleStream.Handle

    Synopsis:    The OS handle of the stream.

Declaration:     Property  Handle  :  Integer

    Visibility:   public

      Access:    Read

Description:     Handle represents the Operating system handle to which reading and writing is done.  The
                handle can be read only, i.e.  it cannot be set after the THandlestream instance was created.
                It should be passed to the constructor THandleStream.Create (294  )

    See also:    THandleStream (293  ), THandleStream.Create (294  )
                2.45          TInterfacedPersistent



                2.45.1         Description

                TInterfacedPersistent is a direct descendent of TPersistent (318  ) which implements the
                #rtl.system.IInterface (1189   ) interface.  In particular, it implements the QueryInterface as
                a public method.
                2.45.2         Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  296       AfterConstruction            Overrides the standard AfterConstruction method.
                __295_______QueryInterface_______________Implementation_of__IInterface.QueryInterface______________________________*
 *___________
                2.45.3         TInterfacedPersistent.QueryInterface

    Synopsis:    Implementation of  IInterface.QueryInterface

Declaration:     function  QueryInterface(const  IID:  TGUID;out  Obj)  :  HResult;    Virtual

    Visibility:   public

Description:     QueryInterface simply calls GetInterface using the specified IID, and returns the correct
                values.

    See also:    #rtl.system.tobject.GetInterface (1354   )



                                                                                 295

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.45.4         TInterfacedPersistent.AfterConstruction

    Synopsis:    Overrides the standard AfterConstruction method.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction is overridden to do some extra interface housekeeping:  a reference to
                the IInterface interface of the owning class is obtained (if it exists).
                2.46          TInterfaceList



                2.46.1         Description

                TInterfaceList is a standard implementation of the IInterfaceList (219  ) interface.  It uses
                a TThreadList (372  ) instance to store the list of interfaces.
                2.46.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  298       Add              Add an interface to the list
                  297       Clear            Removes all interfaces from the list.
                  296       Create           Create a new instance of  TInterfaceList
                  297       Delete           Delete an interface from the list.
                  297       Destroy          Destroys the list of interfaces
                  297       Exchange         Exchange 2 interfaces in the list
                  300       Expand           Expands the list
                  298       First            Returns the first non-Nil element in the list.
                  298       IndexOf          Returns the index of an interface.
                  298       Insert           Insert an interface to the list
                  299       Last             Returns the last non-Nil element in the list.
                  299       Lock             Lock the list
                  299       Remove           Remove an interface from the list
                __299_______Unlock___________UnLocks_a_locked_list_________________________________________________________________*
 *___________
                2.46.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  300       Capacity        rw           The current capacity of the list.
                  300       Count           rw           The current number of elements in the list.
                __300_______Items___________rw___________Array-based_access_to_the_list's_items.___________________________________*
 *___________
                2.46.4         TInterfaceList.Create

    Synopsis:    Create a new instance of  TInterfaceList

Declaration:     constructor  Create

    Visibility:   public

Description:     Create creates a new instance of the TInterfaceList class.  It sets up the internal structures
                needed to store the list of interfaces.

    See also:    TInterfaceList.Destroy (297  )



                                                                                 296

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.46.5         TInterfaceList.Destroy

    Synopsis:    Destroys the list of interfaces

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy first calls Clear (297  ) and then frees the TInterfaceList instance from memory.

                Note that the Clear method decreases the reference count of all interfaces.

    See also:    TInterfaceList.Create (296  ), TInterfaceList.Clear (297  )
                2.46.6         TInterfaceList.Clear

    Synopsis:    Removes all interfaces from the list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear is the implementation of the IInterfaceList.Clear (221  ) method.  It removes all inter-
                faces from the list.  It does this by setting each element in the list to Nil, in this way the
                reference count of each interface in the list is descreased.

    See also:    IInterfaceList.Clear (221  ), TInterfaceList.Add (298  ), TInterfaceList.Destroy (297  ), TList.Clear
                (302  ), TFPList.Clear (288  )
                2.46.7         TInterfaceList.Delete

    Synopsis:    Delete an interface from the list.

Declaration:     procedure  Delete(index:  Integer)

    Visibility:   public

Description:     Delete is the implementation of the IInterfaceList.Delete (221  ) method.  It clears the slot
                first and then removes the element from the list.

    See also:    IInterfaceList.Delete (221  ), TInterfaceList.Remove (299  ), TInterfaceList.Add (298  ), TList.Delete
                (303  ), TFPList.Delete (288  )
                2.46.8         TInterfaceList.Exchange

    Synopsis:    Exchange 2 interfaces in the list

Declaration:     procedure  Exchange(index1:  Integer;index2:  Integer)

    Visibility:   public

Description:     Exchange is the implementation of the IInterfaceList.Exchange (222  ) method.  It exchanges
                the position of 2 interfaces in the list.

    See also:    IInterfaceList.Exchange (222  ), TInterfaceList.Delete (297  ), TInterfaceList.Add (298  ), TList.Exchange
                (303  ), TFPList.Exchange (289  )
                                                                                 297

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.46.9         TInterfaceList.First

    Synopsis:    Returns the first non-Nil element in the list.

Declaration:     function  First  :  IUnknown

    Visibility:   public

Description:     First is the implementation of the IInterfaceList.First (222  ) method.  It returns the first
                non-Nil element from the list.

    See also:    IInterfaceList.First (222  ), TList.First (304  )
                2.46.10          TInterfaceList.IndexOf

    Synopsis:    Returns the index of an interface.

Declaration:     function  IndexOf(item:  IUnknown)  :  Integer

    Visibility:   public

Description:     IndexOf is the implementation of the IInterfaceList.IndexOf (222  ) method.  It returns the
                zero-based index in the list of the indicated interface, or -1 if the index is not in the list.

    See also:    IInterfaceList.IndexOf (222  ), TList.IndexOf (304  )
                2.46.11          TInterfaceList.Add

    Synopsis:    Add an interface to the list

Declaration:     function  Add(item:  IUnknown)  :  Integer

    Visibility:   public

Description:     Add is the implementation of the IInterfaceList.Add (222  ) method.  It adds an interface to
                the list, and returns the location of the new element in the list.  This operation will increment
                the reference count of the interface.

    See also:    IInterfaceList.Add (222  ), TInterfaceList.Delete (297  ), TInterfaceList.Insert (298  ), TList.Add
                (302  ), TFPList.Add (288  )
                2.46.12          TInterfaceList.Insert

    Synopsis:    Insert an interface to the list

Declaration:     procedure  Insert(i:  Integer;item:  IUnknown)

    Visibility:   public

Description:     Insert is the implementation of the IInterfaceList.Insert (222  ) method.  It inserts an inter-
                face in the list at the indicated position.  This operation will increment the reference count
                of the interface.

    See also:    IInterfaceList.Insert (222  ), TInterfaceList.Delete (297  ), TInterfaceList.Add (298  ), TList.Insert
                (304  ), TFPList.Insert (290  )

                                                                                 298

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.46.13          TInterfaceList.Last

    Synopsis:    Returns the last non-Nil element in the list.

Declaration:     function  Last  :  IUnknown

    Visibility:   public

Description:     Last  is  the  implementation  of  the  IInterfaceList.Last  (223  )  method.   It  returns  the  last
                non-Nil element from the list.

    See also:    IInterfaceList.Last (223  ), TInterfaceList.First (298  ), TList.Last (305  ), TFPList.Last (290  )
                2.46.14          TInterfaceList.Remove

    Synopsis:    Remove an interface from the list

Declaration:     function  Remove(item:  IUnknown)  :  Integer

    Visibility:   public

Description:     Remove is the implementation of the IInterfaceList.Remove (223  ) method.  It removes the
                first occurrence of the interface from the list.

    See also:    IInterfaceList.Remove (223  ), TInterfaceList.Delete (297  ), TInterfaceList.IndexOf (298  ), TList.Remove
                (305  ), TFList.Remove (185  )
                2.46.15          TInterfaceList.Lock

    Synopsis:    Lock the list

Declaration:     procedure  Lock

    Visibility:   public

Description:     Lock  locks  the  list.  It  is  the  implementation  of  the  IInterfaceList.Lock  (223  )  method.  It
                limits access to the list to the current thread.

    See also:    IInterfaceList.Lock (223  ), TInterfaceList.UnLock (299  ), TThreadList.LockList (373  )
                2.46.16          TInterfaceList.Unlock

    Synopsis:    UnLocks a locked list

Declaration:     procedure  Unlock

    Visibility:   public

Description:     UnLock unlocks the list.  It is the implementation of the IInterfaceList.UnLock (223  ) method.
                After a call to unlock, the current thread releases the list for manipulation by other threads.

    See also:    IInterfaceList.UnLock (223  ), TInterfaceList.Lock (299  ), TThreadList.UnLockList (373  )


                                                                                 299

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.46.17          TInterfaceList.Expand

    Synopsis:    Expands the list

Declaration:     function  Expand  :  TInterfaceList

    Visibility:   public

Description:     Expand calls the expand method from the internally used list.  It returns itself.

    See also:    TList.Expand (303  )
                2.46.18          TInterfaceList.Capacity

    Synopsis:    The current capacity of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity is the number of elements that the list can contain without needing to allocate
                more memory.

    See also:    IInterfaceList.Capacity (223  ), TInterfaceList.Count (300  ), TList.Capacity (306  ), TFPList.Capacity
                (292  )
                2.46.19          TInterfaceList.Count

    Synopsis:    The current number of elements in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the number of elements in the list.  This can include Nil elements.  Note that the
                elements are zero-based, and thus are indexed from 0 to Count-1.

    See also:    IInterfaceList.Count (224  ), TInterfaceList.Items (300  ), TInterfaceList.Capacity (300  ), TList.Count
                (307  ), TFPList.Count (293  )
                2.46.20          TInterfaceList.Items

    Synopsis:    Array-based access to the list's items.

Declaration:     Property  Items[Index:  Integer]:  IUnknown;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides indexed access to the elements in the list.  Note that the elements are zero-
                based, and thus are indexed from 0 to Count-1.  The items are read-write.  It is not possible
                to add elements to the list by accessing an element with index larger or equal to Count (300  ).

    See also:    IInterfaceList.Items  (224  ),  TInterfaceList.Count  (300  ),  TList.Items  (307  ),  TFPList.Items
                (293  )



                                                                                 300

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.47          TList



                2.47.1         Description

                TList is a class that can be used to manage collections of pointers.  It introduces methods
                and properties to store the pointers, search in the list of pointers, sort them.  It manages its
                memory by itself, no intervention for that is needed.  It has an event notification mechanism
                which allows to notify of list changes.  This slows down some of  TList mechanisms, and if
                no notification is used, TFPList (287  ) may be used instead.

                To  manage  collections  of  strings,  it  is  better  to  use  a  TStrings  (351  )  descendent  such  as
                TStringList (347  ).  To manage general objects, a TCollection (260  ) class exists, from which
                a descendent can be made to manage collections of various kinds.
                2.47.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  302       Add              Adds a new pointer to the list.
                  302       AddList          Add all pointers from another list
                  305       Assign           Copy the contents of another list.
                  302       Clear            Clears the pointer list.
                  301       Create           Class to manage collections of pointers.
                  303       Delete           Removes a pointer from the list.
                  302       Destroy          Destroys the list and releases the memory used to store the list ele-
                                             ments.
                  303       Error            Raises an EListError (215  ) exception.
                  303       Exchange         Exchanges two pointers in the list.
                  303       Expand           Increases the capacity of the list if needed.
                  304       Extract          Remove the first occurrence of a pointer from the list.
                  304       First            Returns the first non-nil pointer in the list.
                  304       IndexOf          Returns the index of a given pointer.
                  304       Insert           Inserts a new pointer in the list at a given position.
                  305       Last             Returns the last non-nil pointer in the list.
                  305       Move             Moves a pointer from one position in the list to another.
                  306       Pack             Removes Nil pointers from the list and frees unused memory.
                  305       Remove           Removes a value from the list.
                __306_______Sort_____________Sorts_the_pointers_in_the_list._______________________________________________________*
 *___________
                2.47.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  306       Capacity        rw           Current capacity (i.e.  number of pointers that can be stored)
                                                         of the list.
                  307       Count           rw           Current number of pointers in the list.
                  307       Items           rw           Provides access to the pointers in the list.
                __307_______List____________r____________Memory_array_where_pointers_are_stored.___________________________________*
 *___________
                2.47.4         TList.Create

    Synopsis:    Class to manage collections of pointers.

Declaration:     constructor  Create

    Visibility:   public
                                                                                 301

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     TList.Create creates a new instance of  TList.  It clears the list and prepares it for use.

    See also:    TList (301  ), TList.Destroy (302  )
                2.47.5         TList.Destroy

    Synopsis:    Destroys the list and releases the memory used to store the list elements.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  destroys  the  list  and  releases  the  memory  used  to  store  the  list  elements.   The
                elements themselves are in no way touched, i.e.  any meomory they point to must be explicitly
                released before calling the destructor.
                2.47.6         TList.AddList

    Synopsis:    Add all pointers from another list

Declaration:     procedure  AddList(AList:  TList)

    Visibility:   public

Description:     AddList adds all pointers from AList to the list.  If a pointer is already present, it is added
                a second time.

    See also:    TList.Assign (305  ), TFPList.AddList (288  )
                2.47.7         TList.Add

    Synopsis:    Adds a new pointer to the list.

Declaration:     function  Add(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Add  adds  a  new  pointer  to  the  list  after  the  last  pointer  (i.e.   at  position  Count,  thus
                increasing  the  item  count  with  1.  If  the  list  is  at  full  capacity,  the  capacity  of  the  list  is
                expanded, using the Grow (301  ) method.

                To insert a pointer at a certain position in the list, use the Insert (304  ) method instead.

    See also:    TList.Delete (303  ), TList.Grow (301  ), TList.Insert (304  )
                2.47.8         TList.Clear

    Synopsis:    Clears the pointer list.

Declaration:     procedure  Clear;    Virtual

    Visibility:   public

Description:     Clear removes all pointers from the list, and sets the capacity to 0, thus freeing any memory
                allocated to maintain the list.

    See also:    TList.Destroy (302  )

                                                                                 302

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.47.9         TList.Delete

    Synopsis:    Removes a pointer from the list.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete removes the pointer at position Index from the list, shifting all following pointers
                one position up (or to the left).

                The memory the pointer is pointing to is not  deallocated.
                2.47.10          TList.Error

    Synopsis:    Raises an EListError (215  ) exception.

Declaration:     procedure  Error(const  Msg:  String;Data:  PtrInt);    Virtual

    Visibility:   public

Description:     Error raises an EListError (215  ) exception, with a message formatted with Msg and Data.
                2.47.11          TList.Exchange

    Synopsis:    Exchanges two pointers in the list.

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer)

    Visibility:   public

Description:     Exchange exchanges the pointers at positions Index1 and Index2.  Both pointers must be
                withing the current range of the list, or an EListError (215  ) exception will be raised.
                2.47.12          TList.Expand

    Synopsis:    Increases the capacity of the list if needed.

Declaration:     function  Expand  :  TList

    Visibility:   public

Description:     Expand increases the capacity of the list if the current element count matches the current
                list capacity.

                The capacity is increased according to the following algorithm:


                     1.If the capacity is less than 3, the capacity is increased with 4.

                     2.If the capacity is larger than 3 and less than 8, the capacity is increased with 8.

                     3.If the capacity is larger than 8, the capacity is increased with 16.


                The return value is Self.

    See also:    TList.Capacity (306  )



                                                                                 303

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.47.13          TList.Extract

    Synopsis:    Remove the first occurrence of a pointer from the list.

Declaration:     function  Extract(item:  Pointer)  :  Pointer

    Visibility:   public

Description:     Extract searched for an occurence of  item, and if a match is found, the match is deleted
                from the list.  If no match is found, nothing is deleted.  If Item was found, the result is Item.
                If Item was not found, the result is Nil.  A lnExtracted notification event is triggered if an
                element is extracted from the list.  Note that a lnDeleted event will also occur.

    See also:    TList.Delete (303  ), TList.IndexOf (304  ), TList.Remove (305  )
                2.47.14          TList.First

    Synopsis:    Returns the first non-nil pointer in the list.

Declaration:     function  First  :  Pointer

    Visibility:   public

Description:     First returns the value of the first non-nil pointer in the list.

                If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

    See also:    TList.Last (305  )
                2.47.15          TList.IndexOf

    Synopsis:    Returns the index of a given pointer.

Declaration:     function  IndexOf(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOf searches for the pointer Item in the list of pointers, and returns the index of the
                pointer, if found.

                If no pointer with the value Item was found, -1 is returned.
                2.47.16          TList.Insert

    Synopsis:    Inserts a new pointer in the list at a given position.

Declaration:     procedure  Insert(Index:  Integer;Item:  Pointer)

    Visibility:   public

Description:     Insert inserts pointer Item at position Index in the list.  All pointers starting from Index
                are shifted to the right.

                If  Index is not a valid position, then a EListError (215  ) exception is raised.

    See also:    TList.Add (302  ), Tlist.Delete (303  )


                                                                                 304

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.47.17          TList.Last

    Synopsis:    Returns the last non-nil pointer in the list.

Declaration:     function  Last  :  Pointer

    Visibility:   public

Description:     Last returns the value of the last non-nil pointer in the list.

                If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

    See also:    TList.First (304  )
                2.47.18          TList.Move

    Synopsis:    Moves a pointer from one position in the list to another.

Declaration:     procedure  Move(CurIndex:  Integer;NewIndex:  Integer)

    Visibility:   public

Description:     Move moves the pointer at position CurIndex to position NewIndex.  This is done by storing
                the value at position CurIndex, deleting the pointer at position CurIndex, and reinserting
                the value at position NewIndex

                If  CurIndex  or  Newindex  are  not  inside  the  valid  range  of  indices,  an  EListError  (215  )
                exception is raised.

    See also:    TList.Exchange (303  )
                2.47.19          TList.Assign

    Synopsis:    Copy the contents of another list.

Declaration:     procedure  Assign(ListA:  TList;AOperator:  TListAssignOp;ListB:  TList)

    Visibility:   public

Description:     Assign copies the pointers of the Obj list to the list.  The list is cleared prior to copying.

    See also:    TList.Clear (302  )
                2.47.20          TList.Remove

    Synopsis:    Removes a value from the list.

Declaration:     function  Remove(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Remove searches Item in the list, and, if it finds it, deletes the item from the list.  Only the
                first occurrence of  Item is removed.

    See also:    TList.Delete (303  ), TList.IndexOf (304  ), Tlist.Insert (304  )



                                                                                 305

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.47.21          TList.Pack

    Synopsis:    Removes Nil pointers from the list and frees unused memory.

Declaration:     procedure  Pack

    Visibility:   public

Description:     Pack  removes  all  nil  pointers  from  the  list.   The  capacity  of  the  list  is  then  set  to  the
                number of pointers in the list.  This method can be used to free unused memory if the list
                has grown to very large sizes and has a lot of unneeded nil pointers in it.

    See also:    TList.Clear (302  )
                2.47.22          TList.Sort

    Synopsis:    Sorts the pointers in the list.

Declaration:     procedure  Sort(Compare:  TListSortCompare)

    Visibility:   public

Description:     Sort>  sorts  the  pointers  in  the  list.  Two  pointers  are  compared  by  passing  them  to  the
                Compare function.  The result of this function determines how the pointers will be sorted:


                      oIf the result of this function is negative,  the first pointer is assumed to be 'less' than
                       the second and will be moved before the second in the list.

                      oIf the function result is positive,  the first pointer is assumed to be 'greater than' the
                       second and will be moved after the second in the list.

                      oif the function result is zero, the pointers are assumed to be 'equal' and no moving will
                       take place.


                The sort is done using a quicksort algorithm.
                2.47.23          TList.Capacity

    Synopsis:    Current capacity (i.e.  number of pointers that can be stored) of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity contains the number of pointers the list can store before it starts to grow.

                If a new pointer is added to the list using add (302  ) or insert (304  ), and there is not enough
                memory to store the new pointer, then the list will try to allocate more memory to store the
                new pointer.  Since this is a time consuming operation, it is important that this operation be
                performed as little as possible.  If it is known how many pointers there will be before filling
                the list,  it is a good idea to set the capacity first before filling.  This ensures that the list
                doesn't need to grow, and will speed up filling the list.

    See also:    TList.SetCapacity (301  ), TList.Count (307  )


                                                                                 306

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.47.24          TList.Count

    Synopsis:    Current number of pointers in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current number of (possibly Nil) pointers in the list.  Since the list is zero-based,
                the index of the largest pointer is Count-1.
                2.47.25          TList.Items

    Synopsis:    Provides access to the pointers in the list.

Declaration:     Property  Items[Index:  Integer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items is used to access the pointers in the list.  It is the default property of the TList class,
                so it can be omitted.

                The list is zero-based, so Index must be in the range 0 to Count-1.
                2.47.26          TList.List

    Synopsis:    Memory array where pointers are stored.

Declaration:     Property  List  :  PPointerList

    Visibility:   public

      Access:    Read

Description:     List points to the memory space where the pointers are stored.  This can be used to quickly
                copy the list of pinters to another location.
                2.48          TMemoryStream



                2.48.1         Description

                TMemoryStream is a TStream (333  ) descendent that stores it's data in memory.  It descends
                directly from TCustomMemoryStream (277  ) and implements the necessary to allocate and
                de-allocate memory directly from the heap.  It implements the Write (309  ) method which is
                missing in TCustomMemoryStream.

                TMemoryStream also introduces methods to load the contents of another stream or a file into
                the memory stream.

                It is not necessary to do any memory management manually, as the stream will allocate or
                de-allocate memory as needed.  When the stream is freed, all allocated memory will be freed
                as well.
                                                                                 307

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.48.2         Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  308       Clear                       Zeroes the position, capacity and size of the stream.
                  308       Destroy                     Frees any allocated memory and destroys the memory stream.
                  309       LoadFromFile                Loads the contents of a file into memory.
                  308       LoadFromStream              Loads the contents of a stream into memory.
                  309       SetSize                     Sets the size for the memory stream.
                __309_______Write_______________________Writes_data_to_the_stream's_memory.________________________________________*
 *___________
                2.48.3         TMemoryStream.Destroy

    Synopsis:    Frees any allocated memory and destroys the memory stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Free clears the memory stream, thus in effect freeing any memory allocated for it, and then
                frees the memory stream.
                2.48.4         TMemoryStream.Clear

    Synopsis:    Zeroes the position, capacity and size of the stream.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear sets the position and size to 0, and sets the capacity of the stream to 0, thus freeing
                all memory allocated for the stream.

    See also:    TStream.Size (342  ), TStream.Position (342  ), TCustomMemoryStream.Memory (279  )
                2.48.5         TMemoryStream.LoadFromStream

    Synopsis:    Loads the contents of a stream into memory.

Declaration:     procedure  LoadFromStream(Stream:  TStream)

    Visibility:   public

Description:     LoadFromStream loads the contents of  Stream into the memorybuffer of the stream.  Any
                previous contents of the memory stream are overwritten.  Memory is allocated as needed.

 Remark:         The LoadFromStream uses the Size (342  ) property of Stream to determine how much memory
                must be allocated.  Some streams do not allow the stream size to be determined, so care must
                be taken when using this method.

                This method will work much faster than the use of the TStream.CopyFrom (336  ) method:


                Seek(0,soFromBeginning);
                    CopyFrom(Stream,Stream.Size);


                because  the  CopyFrom  method  copies  the  contents  in  blocks,  while  LoadFromStream  reads
                the contents of the stream as one big block.

       Errors:   If an error occurs when reading from the stream, an EStreamError (216  ) may occur.

    See also:    TStream.CopyFrom (336  ), TMemoryStream.LoadFromFile (309  )



                                                                                 308

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.48.6         TMemoryStream.LoadFromFile

    Synopsis:    Loads the contents of a file into memory.

Declaration:     procedure  LoadFromFile(const  FileName:  String)

    Visibility:   public

Description:     LoadFromFile loads the contents of the file with name FileName into the memory stream.
                The current contents of the memory stream is replaced by the contents of the file.  Memory
                is allocated as needed.

                The LoadFromFile method simply creates a filestream and then calls the TMemoryStream.LoadFromStream
                (308  ) method.

    See also:    TMemoryStream.LoadFromStream (308  )
                2.48.7         TMemoryStream.SetSize

    Synopsis:    Sets the size for the memory stream.

Declaration:     procedure  SetSize(NewSize:  LongInt);    Override

    Visibility:   public

Description:     SetSize sets the size of the memory stream to NewSize.  This will set the capacity of the
                stream to NewSize and correct the current position in the stream when needed.

    See also:    TStream.Position (342  ), TStream.Size (342  )
                2.48.8         TMemoryStream.Write

    Synopsis:    Writes data to the stream's memory.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write  writes  Count  bytes  from  Buffer  to  the  stream's  memory,  starting  at  the  current
                position in the stream.  If more memory is needed than currently allocated, more memory will
                be allocated.  Any contents in the memory stream at the current position will be overwritten.
                The  function  returns  the  number  of  bytes  actually  written  (which  should  under  normal
                circumstances always equal Count).

                This method overrides the TStream.Write (335  ) method.

       Errors:   If no more memory could be allocated, then an exception will be raised.

    See also:    TCustomMemoryStream.Read (278  )
                2.49          TOwnedCollection



                2.49.1         Description

                TOwnedCollection automatically maintains owner information, so it can be displayed in an
                IDE. Collections that should be displayed in an IDE should descend from TOwnedCollection
                or must implement a GetOwner function.

                                                                                 309

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.49.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __310_______Create__________Create_a_new_TOwnerCollection_instance.________________________________________________*
 *___________
                2.49.3         TOwnedCollection.Create

    Synopsis:    Create a new TOwnerCollection instance.

Declaration:     constructor  Create(AOwner:  TPersistent;AItemClass:  TCollectionItemClass)

    Visibility:   public

Description:     Create  creates  a  new  instance  of  TOwnedCollection  and  stores  the  AOwner  references.
                It  will  the  value  returned  in  the  TCollection.Owner  (261  )  property  of  the  collection.  The
                ItemClass class reference is passed on to the inherited constructor, and will be used to create
                new instances in the Insert (264  ) and Add (262  ) methods.

    See also:    TCollection.Create (261  ), TCollection.Owner (261  )
                2.50          TOwnerStream



                2.50.1         Description

                TOwnerStream can be used when creating stream chains such as when using encryption and
                compression streams.  It keeps a reference to the source stream and will automatically free
                the source stream when ready (if the SourceOwner (311  ) property is set to True).
                2.50.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  310       Create          Create a new instance of  TOwnerStream.
                __311_______Destroy_________Destroys_the_TOwnerStream_instance_and_the_source_stream.______________________________*
 *___________
                2.50.3         Property  overview

                __Page______Property______________Access_______Description_________________________________________________________*
 *___________
                  311       Source                r            Reference to the source stream.
                __311_______SourceOwner___________rw___________Indicates_whether_the_ownerstream_owns_it's_source__________________*
 *___________
                2.50.4         TOwnerStream.Create

    Synopsis:    Create a new instance of  TOwnerStream.

Declaration:     constructor  Create(ASource:  TStream)

    Visibility:   public

Description:     Create instantiates a new instance of  TOwnerStream and stores the reference to AStream.
                If  SourceOwner is True, the soure stream will also be freed when the instance is destroyed.

    See also:    TOwnerStream.Destroy (311  ), TOwnerStream.Source (311  ), TOwnerStream.SourceOwner
                (311  )


                                                                                 310

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.50.5         TOwnerStream.Destroy

    Synopsis:    Destroys the TOwnerStream instance and the source stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy frees the source stream if the SourceOwner property is True.

       Errors:

    See also:    TOwnerStream.Create  (310  ),  TOwnerStream.Source  (311  ),  TOwnerStream.SourceOwner
                (311  )
                2.50.6         TOwnerStream.Source

    Synopsis:    Reference to the source stream.

Declaration:     Property  Source  :  TStream

    Visibility:   public

      Access:    Read

Description:     Source is the source stream.  It should be uses by descendent streams to access the source
                stream to read from or write to.

                Do not free the Source reference directly.  Either the owner stream instance should free the
                source stream or

    See also:    TOwnerStream.Create (310  )
                2.50.7         TOwnerStream.SourceOwner

    Synopsis:    Indicates whether the ownerstream owns it's source

Declaration:     Property  SourceOwner  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     SourceOwner indicates whether the TOwnerStream owns it's Source stream or not.  If this
                property is True then the Source stream is freed when the TOwnerStream instance is freed.

    See also:    TOwnerStream.Source (311  ), TOwnerStream.Destroy (311  )
                2.51          TParser



                2.51.1         Description

                This  class  breaks  a  stream  of  text  data  in  tokens.  Its  primary  use  is  to  help  reading  the
                contents of a form file (usually a file with dfm, xfm or lfm extension), and for this reason it
                isn't suitable to be used as a general parser.

                The parser is always positioned on a certain token, whose type is stored in the Token (317  )
                property.  Various methods are provided to obtain the token value in the desired format.

                To advance to the next token, invoke NextToken (314  ) method.



                                                                                 311

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.51.2         Method  overview

                __Page______Property____________________________Description________________________________________________________*
 *___________
                  313       CheckToken                          Checks whether the token if of the given type.
                  313       CheckTokenSymbol                    Checks whether the token equals the given symbol
                  312       Create                              Creates a new parser instance.
                  312       Destroy                             Destroys the parser instance.
                  313       Error                               Raises an EParserError (216  ) exception with the given
                                                                message
                  313       ErrorFmt                            Raises an EParserError (216  ) exception and formats the
                                                                message.
                  313       ErrorStr                            Raises an EParserError (216  ) exception with the given
                                                                message
                  314       HexToBinary                         Writes hexadecimal data to a stream.
                  314       NextToken                           Reads the next token and returns its type.
                  314       SourcePos                           Returns the current position in the stream.
                  315       TokenComponentIdent                 Returns the path of a subcomponent starting from the
                                                                current token.
                  315       TokenFloat                          Returns the current token as a float.
                  315       TokenInt                            Returns the current token as an integer.
                  316       TokenString                         Returns the current token as a string.
                  316       TokenSymbolIs                       Returns True if the token equals the given symbol.
                __316_______TokenWideString_____________________Returns_the_current_token_as_a_widestring__________________________*
 *___________
                2.51.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                  317       FloatType          r            The type of a float token.
                  317       SourceLine         r            Current source line number.
                __317_______Token______________r____________The_type_of_the_current_token._________________________________________*
 *___________
                2.51.4         TParser.Create

    Synopsis:    Creates a new parser instance.

Declaration:     constructor  Create(Stream:  TStream)

    Visibility:   public

Description:     Create creates a new TParser instance, using Stream as the stream to read data from, and
                reads the first token from the stream.

       Errors:   If an error occours while parsing the first token, an EParserError (216  ) exception is raised.

    See also:    TParser.NextToken (314  ), TParser.Token (317  )
                2.51.5         TParser.Destroy

    Synopsis:    Destroys the parser instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the parser instance.

       Errors:   None.



                                                                                 312

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.51.6         TParser.CheckToken

    Synopsis:    Checks whether the token if of the given type.

Declaration:     procedure  CheckToken(T:  Char)

    Visibility:   public

Description:     Checks whether the token if of the given type.

       Errors:   If current token isn't of type T, an EParserError (216  ) exception is raised.

    See also:    TParser.Token (317  )
                2.51.7         TParser.CheckTokenSymbol

    Synopsis:    Checks whether the token equals the given symbol

Declaration:     procedure  CheckTokenSymbol(const  S:  String)

    Visibility:   public

Description:     CheckTokenSymbol performs a case-insensitive comparison of current token value with S.

                Current token must be of type toSymbol (187  ), otherwise an EParserError (216  ) exception
                is raised.

       Errors:   If the comparison fails, or current token isn't a symbol, an EParserError (216  ) exception is
                raised.

    See also:    TParser.TokenSymbolIs (316  ), toSymbol (187  )
                2.51.8         TParser.Error

    Synopsis:    Raises an EParserError (216  ) exception with the given message

Declaration:     procedure  Error(const  Ident:  String)

    Visibility:   public

Description:     Raises an EParserError (216  ) exception with the given message
                2.51.9         TParser.ErrorFmt

    Synopsis:    Raises an EParserError (216  ) exception and formats the message.

Declaration:     procedure  ErrorFmt(const  Ident:  String;const  Args:  Array  of  const)

    Visibility:   public

Description:     Raises an EParserError (216  ) exception and formats the message.
                2.51.10          TParser.ErrorStr

    Synopsis:    Raises an EParserError (216  ) exception with the given message

Declaration:     procedure  ErrorStr(const  Message:  String)

    Visibility:   public

Description:     Raises an EParserError (216  ) exception with the given message



                                                                                 313

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.51.11          TParser.HexToBinary

    Synopsis:    Writes hexadecimal data to a stream.

Declaration:     procedure  HexToBinary(Stream:  TStream)

    Visibility:   public

Description:     HexToBinary reads a sequence of hexadecimal characters from the input stream and converts
                them to a sequence of bytes which is written to Stream.  Each byte is represented by two
                contiguous hexadecimal characters.

                Whitespace  is  allowed  between  hexadecimal  characters  if  it  doesn't  appear  between  two
                characters that form the same byte.

                HexToBinary stops when the first non-hexadecimal and non-whitespace character is found,
                or the end of the input stream is reached.

 Remark:          This  method  begins  reading  after  the  current  token:  that  is,  current  token,  even  if  it's  a
                valid hexadecimal value, isn't included.

       Errors:   If a single hexadecimal character is found, an EParserError (216  ) exception is raised.
                2.51.12          TParser.NextToken

    Synopsis:    Reads the next token and returns its type.

Declaration:     function  NextToken  :  Char

    Visibility:   public

Description:     NextToken parses the next token in the stream and returns its type.  The type of the token
                can also be retrieved later reading Token (317  ) property.

                If the end of the stream is reached, toEOF (187  ) is returned.

                For details about token types, see TParser.Token (317  )

       Errors:   If an error occours while parsing the token, an EParserError (216  ) exception is raised.

    See also:    TParser.Token (317  )
                2.51.13          TParser.SourcePos

    Synopsis:    Returns the current position in the stream.

Declaration:     function  SourcePos  :  LongInt

    Visibility:   public

Description:Remark:This  is  not  the  character  position  relative  to  the  current  source  line,  but  the  byte  offset
                from the beginning of the stream.

       Errors:   None.

    See also:    TParser.SourceLine (317  )

                                                                                 314

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.51.14          TParser.TokenComponentIdent

    Synopsis:    Returns the path of a subcomponent starting from the current token.

Declaration:     function  TokenComponentIdent  :  String

    Visibility:   public

Description:     If current token is toSymbol (187  ), TokenComponentIdent tries to find subcomponent names
                separated by a dot (.).  The returned string is the longest subcomponent path found.  If there
                are no subcomponents, current symbol is returned.

 Remark:         After this method has been called, subsequent calls to TokenString (316  ) or TokenWideString
                (316  ) return the same value returned by TokenComponentIdent.

                Example

                If source stream contains a.b.c and TParser is positioned on the first token (a), this method
                returns a.b.c.

       Errors:   If Token (317  ) isn't toSymbol (187  ), or no valid symbol is found after a dot, an EParserError
                (216  ) exception is raised.

    See also:    TParser.NextToken (314  ), TParser.Token (317  ), TParser.TokenString (316  ), TParser.TokenWideString
                (316  ), toSymbol (187  )
                2.51.15          TParser.TokenFloat

    Synopsis:    Returns the current token as a float.

Declaration:     function  TokenFloat  :  Extended

    Visibility:   public

Description:     If current token type is toFloat (187  ), this method returns the token value as a float.

                To specify a negative number, no space must exist between unary minus and number.

                Floating point numbers can be postfixed with a character that specifies the floating point
                type.  See FloatType (317  ) for further information.

 Remark:         In the input stream the decimal separator, if present, must be a dot (.).

       Errors:   If Token (317  ) isn't toFloat (187  ), an EParserError (216  ) exception is raised.

    See also:    TParser.FloatType (317  ), TParser.NextToken (314  ), TParser.Token (317  ), toFloat (187  )
                2.51.16          TParser.TokenInt

    Synopsis:    Returns the current token as an integer.

Declaration:     function  TokenInt  :  Int64

    Visibility:   public

Description:     If current token type is toInteger (187  ), this method returns the token value as an integer.

                In the input stream an integer can be an hexadecimal (prefixed by '$' character) or decimal
                number.  Decimal numbers can be prefixed by an unary minus:  if this is the case, no space
                must exist between minus and number.

       Errors:   If Token (317  ) isn't toInteger (187  ), an EConvertError (185  ) exception is raised.

    See also:    TParser.NextToken (314  ), TParser.Token (317  ), toInteger (187  )



                                                                                 315

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.51.17          TParser.TokenString

    Synopsis:    Returns the current token as a string.

Declaration:     function  TokenString  :  String

    Visibility:   public

Description:     If current token type is toString (187  ) or toWString (187  ), this method returns the contents
                of the string.  That is,  enclosing quotes are removed,  embedded quotes are unescaped and
                control strings are converted to the appropriate sequence of characters.

                If current token type isn't a string, a string containing the token representation in the input
                stream  is  returned,  without  any  conversion:   hexadecimal  integers  are  returned  with  the
                leading $, and floating point suffixes like s, c or d are kept.  For tokens whose type isn't a
                special type, return value of  TokenString equals Token (317  ).

 Remark:         If Token (317  ) is toWString (187  ), TokenWideString (316  ) should be used instead.

       Errors:   None.

    See also:    TParser.NextToken (314  ), TParser.TokenWideString (316  ), TParser.Token (317  ), toString
                (187  ), toWString (187  )
                2.51.18          TParser.TokenWideString

    Synopsis:    Returns the current token as a widestring

Declaration:     function  TokenWideString  :  WideString

    Visibility:   public

Description:     If  current  token  type  is  toWString  (187  ),  this  method  returns  the  contents  of  the  string.
                That is, enclosing quotes are removed, embedded quotes are unescaped and control strings
                are converted to the appropriate sequence of characters.

                If current token isn't a widestring, TokenWideString behaviour is the same as TokenString
                (316  ).

       Errors:   None.

    See also:    TParser.NextToken (314  ), TParser.TokenString (316  ), TParser.Token (317  ), toWString (187  )
                2.51.19          TParser.TokenSymbolIs

    Synopsis:    Returns True if the token equals the given symbol.

Declaration:     function  TokenSymbolIs(const  S:  String)  :  Boolean

    Visibility:   public

Description:     TokenSymbolIs performs a case-insensitive comparison of current token value with S.

                If current token isn't of type toSymbol (187  ), or comparison fails, False is returned.

       Errors:   None.

    See also:    TParser.CheckTokenSymbol (313  ), TParser.Token (317  )

                                                                                 316

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.51.20          TParser.FloatType

    Synopsis:    The type of a float token.

Declaration:     Property  FloatType  :  Char

    Visibility:   public

      Access:    Read

Description:     Floating  point  numbers  can  be  postfixed  with  a  character  specifying  the  type  of  floating
                point value.  When specified, this property holds the character postfixed to the number.

                It can be one of the following values:



                                                                       Table 2.19:

                                                            s or S      Value is a single.
                                                            c or C      Value is a currency.
                                                            d or D      Value is a date.
                If Token (317  ) isn't toFloat (187  ) or one of the above characters wasn't specified, FloatType
                is the null character (zero).

    See also:    TParser.NextToken (314  ), TParser.Token (317  ), TParser.TokenFloat (315  ), toFloat (187  )
                2.51.21          TParser.SourceLine

    Synopsis:    Current source line number.

Declaration:     Property  SourceLine  :  Integer

    Visibility:   public

      Access:    Read

Description:     Current source line number.

    See also:    TParser.SourcePos (314  )
                2.51.22          TParser.Token

    Synopsis:    The type of the current token.

Declaration:     Property  Token  :  Char

    Visibility:   public

      Access:    Read

Description:     This property holds the type of the current token.  When Token isn't one of the special token
                types (whose value can be retrieved with specific methods) it is the character representing
                the current token.

                Special token types:

                To advance to the next token, use NextToken (314  ) method.

    See also:    TParser.CheckToken (313  ), TParser.NextToken (314  ), TParser.TokenComponentIdent (315  ),
                TParser.TokenFloat (315  ), TParser.TokenInt (315  ), TParser.TokenString (316  ), TParser.TokenWideString
                (316  )



                                                                                 317

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________

                                                                       Table 2.20:



                  toEOF (187  )              Value returned by TParser.Token (317  ) when the end of the input stream was reached.
                  toSymbol (187  )           Value returned by TParser.Token (317  ) when a symbol was found in the input stream.
                  toString (187  )           Value returned by TParser.Token (317  ) when a string was found in the input stream.
                  toInteger (187  )          Value returned by TParser.Token (317  ) when an integer was found in the input stream.
                  toFloat (187  )            Value returned by TParser.Token (317  ) when a floating point value was found in the i*
 *nput stream.
                  toWString (187  )          Value returned by TParser.Token (317  ) when a widestring was found in the input strea*
 *m.

                2.52          TPersistent



                2.52.1         Description

                TPersistent is the basic class for the streaming system.  Since it is compiled in the {$M+}
                state, the compiler generates RTTI (Run-Time Type Information) for it and all classes that
                descend from it.  This information can be used to stream all properties of classes.

                It also introduces functionality to assign the contents of 2 classes to each other.
                2.52.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  318       Assign                  Assign the contents of one class to another.
                  318       Destroy                 Destroys the TPersistent instance.
                __319_______GetNamePath_____________Returns_a_string_that_can_be_used_to_identify_the_class_instance.______________*
 *___________
                2.52.3         TPersistent.Destroy

    Synopsis:    Destroys the TPersistent instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  disposes  of  the  persistent  object.   This  method  should  never  be  called  directly.
                Instead the Free method should be used.
                2.52.4         TPersistent.Assign

    Synopsis:    Assign the contents of one class to another.

Declaration:     procedure  Assign(Source:  TPersistent);    Virtual

    Visibility:   public

Description:     Assign copies the contents of  Source to Self, if the classes of the destination and source
                classes are compatible.

                The  TPersistent  implementation  of  Assign  does  nothing  but  calling  the  AssignTo  (318  )
                method  of  source.   This  means  that  if  the  destination  class  does  not  know  how  to  assign
                the  contents  of  the  source  class,  the  source  class  instance  is  asked  to  assign  itself  to  the
                destination class.  This means that it is necessary to implement only one of the two methods
                so that two classes can be assiged to one another.

 Remark:         In general, a statement of the form



                                                                                 318

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                Destination:=Source;


                (where Destination and Source are classes) does not achieve the same as a statement of
                the form


                Destination.Assign(Source);


                After the former statement,  both Source and Destination will point to the same object.
                The latter statemtent will copy the contents  of the Source class to the Destination class.

    See also:    TPersistent.AssignTo (318  )
                2.52.5         TPersistent.GetNamePath

    Synopsis:    Returns a string that can be used to identify the class instance.

Declaration:     function  GetNamePath  :  String;    Virtual

    Visibility:   public

Description:     GetNamePath returns a string that can be used to identify the class instance.  This can be
                used to display a name for this instance in a Object designer.

                GetNamePath  constructs  a  name  by  recursively  prepending  the  Classname  of  the  Owner
                instance to the Classname of this instance, separated by a dot.

    See also:    TPersistent.GetOwner (318  )
                2.53          TReader



                2.53.1         Description

                The TReader class is a reader class that implements generic component streaming capabil-
                ities, independent of the format of the data in the stream.  It uses a driver class TAbstrac-
                tObjectReader (226  ) to do the actual reading of data.  The interface of the TReader class
                should be identical to the interface in Delphi.



                                                                                 319

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
2.53.2         Method  overview

__Page______Property__________________________Description_____________________________________________________________________
  321       BeginReferences                   Initializes the component referencing mechanism.
  322       CheckValue                        Raises an exception if the next value in the stream is not
                                              of type Value
  327       CopyValue                         Copy a value to a writer.
  321       Create                            Creates a new reader class
  322       DefineBinaryProperty              Reads a user-defined binary property from the stream.
  322       DefineProperty                    Reads a user-defined property from the stream.
  321       Destroy                           Destroys a reader class.
  322       EndOfList                         Returns true if the stream contains an end-of-list marker.
  322       EndReferences                     Finalizes the component referencing mechanism.
  323       FixupReferences                   Tries to resolve all unresolved component references.
  323       NextValue                         Returns the type of the next value.
  323       Read                              Read raw data from stream
  323       ReadBoolean                       Reads a boolean from the stream.
  323       ReadChar                          Reads a character from the stream.
  324       ReadCollection                    Reads a collection from the stream.
  324       ReadComponent                     Starts reading a component from the stream.
  324       ReadComponents                    Starts reading child components from the stream.
  325       ReadCurrency                      Read a currency value from the stream.
  325       ReadDate                          Reads a date from the stream
  324       ReadFloat                         Reads a float from the stream.
  325       ReadIdent                         Reads an identifier from the stream.
  326       ReadInt64                         Reads a 64-bit integer from the stream.
  325       ReadInteger                       Reads an integer from the stream
  326       ReadListBegin                     Checks for the beginning of a list.
  326       ReadListEnd                       Checks for the end of a list.
  326       ReadRootComponent                 Starts reading a root component.
  325       ReadSingle                        Reads a single-type real from the stream.
  326       ReadString                        Reads a string from the stream.
  327       ReadValue                         Reads the next value type from the stream.
  324       ReadWideChar                      Read widechar from the stream
__327_______ReadWideString____________________Read_a_WideString_value_from_the_stream.________________________________________

                                                                 320

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.3         Property  overview

                __Page______Property______________________________Access_______Description_________________________________________*
 *___________
                  327       Driver                                r            The driver in use for streaming the data.
                  329       OnAncestorNotFound                    rw           Handler called when the ancestor component
                                                                               cannot be found.
                  329       OnCreateComponent                     rw           Handler  called  when  a  component  needs  to
                                                                               be created.
                  328       OnError                               rw           Handler called when an error occurs.
                  330       OnFindComponentClass                  rw           Handler called when a component class refer-
                                                                               ence needs to be found.
                  328       OnFindMethod                          rw           Handler to find or change a method address.
                  328       OnPropertyNotFound                    rw           Handler for treating missing properties.
                  330       OnReadStringProperty                  rw           Handler  for  translating  strings  when  read
                                                                               from the stream.
                  329       OnReferenceName                       rw           Handler  called  when  another  component  is
                                                                               referenced.
                  329       OnSetMethodProperty                   rw           Handler for setting method properties.
                  329       OnSetName                             rw           Handler  called  when  setting  a  component
                                                                               name.
                  327       Owner                                 rw           Owner of the component being read
                __328_______Parent________________________________rw___________Parent_of_the_component_being_read._________________*
 *___________
                2.53.4         TReader.Create

    Synopsis:    Creates a new reader class

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Creates a new reader class
                2.53.5         TReader.Destroy

    Synopsis:    Destroys a reader class.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys a reader class.
                2.53.6         TReader.BeginReferences

    Synopsis:    Initializes the component referencing mechanism.

Declaration:     procedure  BeginReferences

    Visibility:   public

Description:     Initializes the component referencing mechanism.


                                                                                 321

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.7         TReader.CheckValue

    Synopsis:    Raises an exception if the next value in the stream is not of type Value

Declaration:     procedure  CheckValue(Value:  TValueType)

    Visibility:   public

Description:     Raises an exception if the next value in the stream is not of type Value
                2.53.8         TReader.DefineProperty

    Synopsis:    Reads a user-defined property from the stream.

Declaration:     procedure  DefineProperty(const  Name:  String;AReadData:  TReaderProc;
                                                        WriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Override

    Visibility:   public

Description:     Reads a user-defined property from the stream.
                2.53.9         TReader.DefineBinaryProperty

    Synopsis:    Reads a user-defined binary property from the stream.

Declaration:     procedure  DefineBinaryProperty(const  Name:  String;
                                                                  AReadData:  TStreamProc;
                                                                  WriteData:  TStreamProc;HasData:  Boolean)
                                                                  ;    Override

    Visibility:   public

Description:     Reads a user-defined binary property from the stream.
                2.53.10          TReader.EndOfList

    Synopsis:    Returns true if the stream contains an end-of-list marker.

Declaration:     function  EndOfList  :  Boolean

    Visibility:   public

Description:     Returns true if the stream contains an end-of-list marker.
                2.53.11          TReader.EndReferences

    Synopsis:    Finalizes the component referencing mechanism.

Declaration:     procedure  EndReferences

    Visibility:   public

Description:     Finalizes the component referencing mechanism.

                                                                                 322

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.12          TReader.FixupReferences

    Synopsis:    Tries to resolve all unresolved component references.

Declaration:     procedure  FixupReferences

    Visibility:   public

Description:     Tries to resolve all unresolved component references.
                2.53.13          TReader.NextValue

    Synopsis:    Returns the type of the next value.

Declaration:     function  NextValue  :  TValueType

    Visibility:   public

Description:     Returns the type of the next value.
                2.53.14          TReader.Read

    Synopsis:    Read raw data from stream

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual

    Visibility:   public

Description:     Read is introduced for Delphi compatibility to read raw data from the component stream.
                This should not be used in new production code as it will totally mess up the streaming.

    See also:    TAbstractObjectReader.Read (228  ), TBinaryObjectReader.Read (246  )
                2.53.15          TReader.ReadBoolean

    Synopsis:    Reads a boolean from the stream.

Declaration:     function  ReadBoolean  :  Boolean

    Visibility:   public

Description:     Reads a boolean from the stream.
                2.53.16          TReader.ReadChar

    Synopsis:    Reads a character from the stream.

Declaration:     function  ReadChar  :  Char

    Visibility:   public

Description:     Reads a character from the stream.

                                                                                 323

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.17          TReader.ReadWideChar

    Synopsis:    Read widechar from the stream

Declaration:     function  ReadWideChar  :  WideChar

    Visibility:   public

Description:     TReader.ReadWideChar reads a widechar from the stream.  This actually reads a widestring
                and returns the first character.

    See also:    TReader.ReadWideString (327  ), TWriter.WriteWideChar (377  )
                2.53.18          TReader.ReadCollection

    Synopsis:    Reads a collection from the stream.

Declaration:     procedure  ReadCollection(Collection:  TCollection)

    Visibility:   public

Description:     Reads a collection from the stream.
                2.53.19          TReader.ReadComponent

    Synopsis:    Starts reading a component from the stream.

Declaration:     function  ReadComponent(Component:  TComponent)  :  TComponent

    Visibility:   public

Description:     Starts reading a component from the stream.
                2.53.20          TReader.ReadComponents

    Synopsis:    Starts reading child components from the stream.

Declaration:     procedure  ReadComponents(AOwner:  TComponent;AParent:  TComponent;
                                                        Proc:  TReadComponentsProc)

    Visibility:   public

Description:     Starts reading child components from the stream.
                2.53.21          TReader.ReadFloat

    Synopsis:    Reads a float from the stream.

Declaration:     function  ReadFloat  :  Extended

    Visibility:   public

Description:     Reads a float from the stream.
                                                                                 324

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.22          TReader.ReadSingle

    Synopsis:    Reads a single-type real from the stream.

Declaration:     function  ReadSingle  :  Single

    Visibility:   public

Description:     Reads a single-type real from the stream.
                2.53.23          TReader.ReadCurrency

    Synopsis:    Read a currency value from the stream.

Declaration:     function  ReadCurrency  :  Currency

    Visibility:   public

Description:     ReadCurrency reads a currency typed value from the stream and returns the result.  This
                method does nothing except call the driver method of the driver being used.

    See also:    TWriter.WriteCurrency (377  )
                2.53.24          TReader.ReadDate

    Synopsis:    Reads a date from the stream

Declaration:     function  ReadDate  :  TDateTime

    Visibility:   public

Description:     Reads a date from the stream
                2.53.25          TReader.ReadIdent

    Synopsis:    Reads an identifier from the stream.

Declaration:     function  ReadIdent  :  String

    Visibility:   public

Description:     Reads an identifier from the stream.
                2.53.26          TReader.ReadInteger

    Synopsis:    Reads an integer from the stream

Declaration:     function  ReadInteger  :  LongInt

    Visibility:   public

Description:     Reads an integer from the stream

                                                                                 325

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.27          TReader.ReadInt64

    Synopsis:    Reads a 64-bit integer from the stream.

Declaration:     function  ReadInt64  :  Int64

    Visibility:   public

Description:     Reads a 64-bit integer from the stream.
                2.53.28          TReader.ReadListBegin

    Synopsis:    Checks for the beginning of a list.

Declaration:     procedure  ReadListBegin

    Visibility:   public

Description:     Checks for the beginning of a list.
                2.53.29          TReader.ReadListEnd

    Synopsis:    Checks for the end of a list.

Declaration:     procedure  ReadListEnd

    Visibility:   public

Description:     Checks for the end of a list.
                2.53.30          TReader.ReadRootComponent

    Synopsis:    Starts reading a root component.

Declaration:     function  ReadRootComponent(ARoot:  TComponent)  :  TComponent

    Visibility:   public

Description:     Starts reading a root component.
                2.53.31          TReader.ReadString

    Synopsis:    Reads a string from the stream.

Declaration:     function  ReadString  :  String

    Visibility:   public

Description:     Reads a string from the stream.


                                                                                 326

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.32          TReader.ReadWideString

    Synopsis:    Read a WideString value from the stream.

Declaration:     function  ReadWideString  :  WideString

    Visibility:   public

Description:     ReadWidestring  reads  a  widestring  typed  value  from  the  stream  and  returns  the  result.
                This method does nothing except call the driver method of the driver being used.

    See also:    TWriter.WriteWideString (379  )
                2.53.33          TReader.ReadValue

    Synopsis:    Reads the next value type from the stream.

Declaration:     function  ReadValue  :  TValueType

    Visibility:   public

Description:     Reads the next value type from the stream.
                2.53.34          TReader.CopyValue

    Synopsis:    Copy a value to a writer.

Declaration:     procedure  CopyValue(Writer:  TWriter)

    Visibility:   public

Description:     Copy a value to a writer.
                2.53.35          TReader.Driver

    Synopsis:    The driver in use for streaming the data.

Declaration:     Property  Driver  :  TAbstractObjectReader

    Visibility:   public

      Access:    Read

Description:     The driver in use for streaming the data.
                2.53.36          TReader.Owner

    Synopsis:    Owner of the component being read

Declaration:     Property  Owner  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     Owner of the component being read
                                                                                 327

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.37          TReader.Parent

    Synopsis:    Parent of the component being read.

Declaration:     Property  Parent  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     Parent of the component being read.
                2.53.38          TReader.OnError

    Synopsis:    Handler called when an error occurs.

Declaration:     Property  OnError  :  TReaderError

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when an error occurs.
                2.53.39          TReader.OnPropertyNotFound

    Synopsis:    Handler for treating missing properties.

Declaration:     Property  OnPropertyNotFound  :  TPropertyNotFoundEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnPropertyNotFound can be used to take appropriate action when a property is read from
                a stream and no such property is found in the RTTI information of the Instance that is being
                read from the stream.  It can be set at runtime, or at designtime by an IDE.

                For more information about the meaning of the various arguments to the event handler, see
                TPropertyNotFoundEvent (194  ).

    See also:    TPropertyNotFoundEvent (194  ), TReader.OnSetMethodProperty (329  ), TReader.OnReadStringProperty
                (330  )
                2.53.40          TReader.OnFindMethod

    Synopsis:    Handler to find or change a method address.

Declaration:     Property  OnFindMethod  :  TFindMethodEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler to find or change a method address.



                                                                                 328

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.41          TReader.OnSetMethodProperty

    Synopsis:    Handler for setting method properties.

Declaration:     Property  OnSetMethodProperty  :  TSetMethodPropertyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnSetMethodProperty can be set to handle the setting of method properties.  This handler
                can  be  used  by  an  IDE  to  prevent  methods  from  actually  being  when  an  object  is  being
                streamed in the designer.

    See also:    TReader.OnReadStringProperty (330  ), TReader.OnPropertyNotFound (328  )
                2.53.42          TReader.OnSetName

    Synopsis:    Handler called when setting a component name.

Declaration:     Property  OnSetName  :  TSetNameEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when setting a component name.
                2.53.43          TReader.OnReferenceName

    Synopsis:    Handler called when another component is referenced.

Declaration:     Property  OnReferenceName  :  TReferenceNameEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when another component is referenced.
                2.53.44          TReader.OnAncestorNotFound

    Synopsis:    Handler called when the ancestor component cannot be found.

Declaration:     Property  OnAncestorNotFound  :  TAncestorNotFoundEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when the ancestor component cannot be found.
                2.53.45          TReader.OnCreateComponent

    Synopsis:    Handler called when a component needs to be created.

Declaration:     Property  OnCreateComponent  :  TCreateComponentEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when a component needs to be created.



                                                                                 329

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.53.46          TReader.OnFindComponentClass

    Synopsis:    Handler called when a component class reference needs to be found.

Declaration:     Property  OnFindComponentClass  :  TFindComponentClassEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when a component class reference needs to be found.
                2.53.47          TReader.OnReadStringProperty

    Synopsis:    Handler for translating strings when read from the stream.

Declaration:     Property  OnReadStringProperty  :  TReadWriteStringPropertyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnReadStringProperty  is  called  whenever  a  string  property  is  read  from  the  stream.  It
                can  be  used  e.g.   by  a  translation  mechanism  to  translate  the  strings  on  the  fly,  when  a
                form is loaded.  See TReadWriteStringPropertyEvent (195  ) for a description of the various
                parameters.

    See also:    TReader.OnPropertyNotFound (328  ), TReader.OnSetMethodProperty (329  ), TReadWriteString-
                PropertyEvent (195  )
                2.54          TRecall



                2.54.1         Description

                TRecall is a helper class used to copy published properties of a class (the reference object)
                in  another  class  (the  storage  object).   The  reference  object  and  storage  object  must  be
                assignable to each other.

                The  TRecall  can  be  used  to  store  the  state  of  a  persistent  class,  and  restore  it  at  a  later
                time.

                When a TRecall object is created, it gets passed a reference instance and a storage instance.
                It immediatly stores the properties of the reference object in the storage object.

                The  Store  (331  )  method  can  be  called  throughout  the  lifetime  of  the  reference  object  to
                update the stored properties.

                When  the  TRecall  instance  is  destroyed  then  the  properties  are  copied  from  the  storage
                object to the reference object.  The storage object is freed automatically.

                If  the  properties  should  not  be  copied  back  from  the  storage  to  the  reference  object,  the
                Forget (332  ) can be called.
                                                                                 330

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.54.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  331       Create          Creates a new instance of  TRecall.
                  331       Destroy         Copies the stored properties to the reference object and destroys the
                                            TRecall instance.
                  332       Forget          Clear the reference property.
                __331_______Store___________Assigns_the_reference_instance_to_the_storage_instance.________________________________*
 *___________
                2.54.3         Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __332_______Reference________r____________The_reference_object.____________________________________________________*
 *___________
                2.54.4         TRecall.Create

    Synopsis:    Creates a new instance of  TRecall.

Declaration:     constructor  Create(AStorage:  TPersistent;AReference:  TPersistent)

    Visibility:   public

Description:     Create  creates  a  new  instance  of  TRecall  and  initializes  the  Reference  and  Storage  in-
                stances.  It calls Store (331  ) to assign the reference object properties to the storage instance.

    See also:    TRecall.Store (331  ), TRecall.Destroy (331  )
                2.54.5         TRecall.Destroy

    Synopsis:    Copies the stored properties to the reference object and destroys the TRecall instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  assigns  the  storage  instance  to  the  reference  instance,  if  the  latter  is  still  valid.
                After this, it frees the storage and calls the inherited destroy.

       Errors:   Destroy does not check whether the reference (332  ) instance is still valid.  If the reference
                pointer was invalidated, call TRecall.Forget (332  ) to clear the reference instance.

    See also:    TRecall.Store (331  ), TRecall.Forget (332  )
                2.54.6         TRecall.Store

    Synopsis:    Assigns the reference instance to the storage instance.

Declaration:     procedure  Store

    Visibility:   public

Description:     Store assigns the reference instance to the storage instance.  This will only work if the two
                classes can be assigned to each other.

                This method can be used to refresh the storage.

       Errors:   Store  does  not  check  whether  the  reference  (332  )  instance  is  still  valid.  If  the  reference
                pointer was invalidated, call TRecall.Forget (332  ) to clear the reference instance.



                                                                                 331

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.54.7         TRecall.Forget

    Synopsis:    Clear the reference property.

Declaration:     procedure  Forget

    Visibility:   public

Description:     Forget sets the Reference (185  ) property to Nil.  When the TRecall instance is destroyed,
                the reference instance will not be restored.

                Note that after a call to Forget, a call to Store (331  ) has no effect.

       Errors:   None.

    See also:    TRecall.Reference (332  ), TRecall.Store (331  ), TRecall.Destroy (331  )
                2.54.8         TRecall.Reference

    Synopsis:    The reference object.

Declaration:     Property  Reference  :  TPersistent

    Visibility:   public

      Access:    Read

Description:     Reference is the instance of the reference object.  Do not free the reference directly.  Call
                Forget (332  ) to clear the reference and then free the reference object.

    See also:    TRecall.Forget (332  )
                2.55          TResourceStream



                2.55.1         Description

                Stream that reads its data from a resource object.
                2.55.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  332       Create                  Creates a new instance of a resource stream.
                  333       CreateFromID            Creates a new instance of a resource stream with resource
                __333_______Destroy_________________Destroys_the_instance_of_the_resource_stream.__________________________________*
 *___________
                2.55.3         TResourceStream.Create

    Synopsis:    Creates a new instance of a resource stream.

Declaration:     constructor  Create(Instance:  THandle;const  ResName:  String;
                                              ResType:  PChar)

    Visibility:   public

Description:     Creates a new instance of a resource stream.



                                                                                 332

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.55.4         TResourceStream.CreateFromID

    Synopsis:    Creates a new instance of a resource stream with resource

Declaration:     constructor  CreateFromID(Instance:  THandle;ResID:  Integer;
                                                        ResType:  PChar)

    Visibility:   public

Description:     Creates a new instance of a resource stream with resource
                2.55.5         TResourceStream.Destroy

    Synopsis:    Destroys the instance of the resource stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the instance of the resource stream.
                2.56          TStream



                2.56.1         Description

                TStream  is  the  base  class  for  all  streaming  classes.   It  defines  methods  for  reading  (334  ),
                writing (335  ) from and to streams, as well as functions to determine the size of the stream
                as well as the current position of the stream.

                Descendent classes such as TMemoryStream (307  ) or TFileStream (285  ) then override these
                methods to write streams to memory or file.


                                                                                 333

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.2         Method  overview

                __Page______Property__________________________Description__________________________________________________________*
 *___________
                  336       CopyFrom                          Copy data from one stream to another
                  339       FixupResourceHeader               Not implemented in FPC
                  334       Read                              Reads data from the stream to a buffer and returns the
                                                              number of bytes read.
                  340       ReadAnsiString                    Read an ansistring from the stream and return its value.
                  336       ReadBuffer                        Reads data from the stream to a buffer
                  339       ReadByte                          Read a byte from the stream and return its value.
                  337       ReadComponent                     Reads component data from a stream
                  337       ReadComponentRes                  Reads component data and resource header from a stream
                  340       ReadDWord                         Read a DWord from the stream and return its value.
                  339       ReadResHeader                     Read a resource header from the stream.
                  340       ReadWord                          Read a word from the stream and return its value.
                  335       Seek                              Sets the current position in the stream
                  335       Write                             Writes data from a buffer to the stream and returns the
                                                              number of bytes written.
                  341       WriteAnsiString                   Write an ansistring to the stream.
                  336       WriteBuffer                       Writes data from the stream to the buffer
                  340       WriteByte                         Write a byte to the stream.
                  337       WriteComponent                    Write component data to the stream
                  338       WriteComponentRes                 Write resource header and component data to a stream
                  338       WriteDescendent                   Write component data to a stream, relative to an ancestor
                  338       WriteDescendentRes                Write resource header and component data to a stream,
                                                              relative to an ancestor
                  341       WriteDWord                        Write a DWord to the stream.
                  338       WriteResourceHeader               Write resource header to the stream
                __341_______WriteWord_________________________Write_a_word_to_the_stream.__________________________________________*
 *___________
                2.56.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  342       Position        rw           The current position in the stream.
                __342_______Size____________rw___________The_current_size_of_the_stream.___________________________________________*
 *___________
                2.56.4         TStream.Read

    Synopsis:    Reads data from the stream to a buffer and returns the number of bytes read.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Virtual

    Visibility:   public

Description:     Read attempts to read Count from the stream to Buffer and returns the number of bytes
                actually read.

                This  method  should  be  used  when  the  number  of  bytes  is  not  determined.   If  a  specific
                number of bytes is expected, use TSTream.ReadBuffer (336  ) instead.

                As implemented in TStream, Read does nothing but raises an EStreamError (216  ) exception
                to indicate that reading is not supported.  Descendent classes that allow reading must override
                this method to do the actual reading.

       Errors:   In case a descendent class does not allow reading from the stream, an exception is raised.

    See also:    TStream.Write (335  ), TStream.ReadBuffer (336  )



                                                                                 334

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.5         TStream.Write

    Synopsis:    Writes data from a buffer to the stream and returns the number of bytes written.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Virtual

    Visibility:   public

Description:     Write  attempts  to  write  Count  bytes  from  Buffer  to  the  stream.   It  returns  the  actual
                number of bytes written to the stream.

                This  method  should  be  used  when  the  number  of  bytes  that  should  be  written  is  not  de-
                termined.  If a specific number of bytes should be written, use TSTream.WriteBuffer (336  )
                instead.

                As implemented in TStream, Write does nothing but raises EStreamError (216  ) exception to
                indicate that writing is not supported.  Descendent classes that allow writing must override
                this method to do the actual writing.

       Errors:   In case a descendent class does not allow writing to the stream, an exception is raised.

    See also:    TStream.Read (334  ), TStream.WriteBuffer (336  )
                2.56.6         TStream.Seek

    Synopsis:    Sets the current position in the stream

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Virtual
                                      ;    Overload
                function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64;    Virtual
                                      ;    Overload

    Visibility:   public

Description:     Seek sets the position of the stream to Offset bytes from Origin.  Origin can have one of
                the following values:



                                                                       Table 2.21:

                           Constant                    Meaning
                           soFromBeginning             Set the position relative to the start of the stream.
                           soFromCurrent               Set the position relative to the beginning of the stream.
                           soFromEnd                   Set the position relative to the end of the stream.
                Offset should be negative when the origin is SoFromEnd.  It should be positive for soFromBeginning
                and can have both signs for soFromCurrent

                This  is  an  abstract  method,  which  must  be  overridden  by  descendent  classes.   They  may
                choose not to implement this method for all values of  Origin and Offset.

       Errors:   An exception may be raised if this method is called with an invalid pair of  Offset,Origin
                values.  e.g.  a negative offset for soFromBeginning.

    See also:    TStream.Position (342  )


                                                                                 335

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.7         TStream.ReadBuffer

    Synopsis:    Reads data from the stream to a buffer

Declaration:     procedure  ReadBuffer(var  Buffer;Count:  LongInt)

    Visibility:   public

Description:     ReadBuffer reads Count bytes of the stream into Buffer.  If the stream does not contain
                Count bytes, then an exception is raised.

                ReadBuffer should be used to read in a fixed number of bytes, such as when reading struc-
                tures or the content of variables.  If the number of bytes is not determined, use TStream.Read
                (334  ) instead.  ReadBuffer uses Read internally to do the actual reading.

       Errors:   If the stream does not allow to read Count bytes, then an exception is raised.

    See also:    TStream.Read (334  ), TStream.WriteBuffer (336  )
                2.56.8         TStream.WriteBuffer

    Synopsis:    Writes data from the stream to the buffer

Declaration:     procedure  WriteBuffer(const  Buffer;Count:  LongInt)

    Visibility:   public

Description:     WriteBuffer writes Count bytes to the stream from Buffer.  If the stream does not allow
                Count bytes to be written, then an exception is raised.

                WriteBuffer should be used to read in a fixed number of bytes, such as when writing struc-
                tures or the content of variables.  If the number of bytes is not determined, use TStream.Write
                (335  ) instead.  WriteBuffer uses Write internally to do the actual reading.

       Errors:   If the stream does not allow to write Count bytes, then an exception is raised.

    See also:    TStream.Write (335  ), TStream.ReadBuffer (336  )
                2.56.9         TStream.CopyFrom

    Synopsis:    Copy data from one stream to another

Declaration:     function  CopyFrom(Source:  TStream;Count:  Int64)  :  Int64

    Visibility:   public

Description:     CopyFrom  reads  Count  bytes  from  Source  and  writes  them  to  the  current  stream.   This
                updates  the  current  position  in  the  stream.  After  the  action  is  completed,  the  number  of
                bytes copied is returned.

                This  can  be  used  to  quickly  copy  data  from  one  stream  to  another  or  to  copy  the  whole
                contents of the stream.

    See also:    TStream.Read (334  ), TStream.Write (335  )


                                                                                 336

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.10          TStream.ReadComponent

    Synopsis:    Reads component data from a stream

Declaration:     function  ReadComponent(Instance:  TComponent)  :  TComponent

    Visibility:   public

Description:     ReadComponent reads a component state from the stream and transfers this state to Instance.
                If Instance is nil, then it is created first based on the type stored in the stream.  ReadComponent
                returns the component as it is read from the stream.

                ReadComponent  simply  creates  a  TReader  (319  )  object  and  calls  its  ReadRootComponent
                (326  ) method.

       Errors:   If an error occurs during the reading of the component, an EFilerError (215  ) exception is
                raised.

    See also:    TStream.WriteComponent (337  ), TStream.ReadComponentRes (337  ), TReader.ReadRootComponent
                (326  )
                2.56.11          TStream.ReadComponentRes

    Synopsis:    Reads component data and resource header from a stream

Declaration:     function  ReadComponentRes(Instance:  TComponent)  :  TComponent

    Visibility:   public

Description:     ReadComponentRes reads a resource header from the stream, and then calls ReadComponent
                (337  ) to read the component state from the stream into Instance.

                This  method  is  usually  called  by  the  global  streaming  method  when  instantiating  forms
                and  datamodules  as  created  by  an  IDE.  It  should  be  used  mainly  on  Windows,  to  store
                components in Windows resources.

       Errors:   If an error occurs during the reading of the component, an EFilerError (215  ) exception is
                raised.

    See also:    TStream.ReadComponent (337  ), TStream.WriteComponentRes (338  )
                2.56.12          TStream.WriteComponent

    Synopsis:    Write component data to the stream

Declaration:     procedure  WriteComponent(Instance:  TComponent)

    Visibility:   public

Description:     WriteComponent  writes  the  published  properties  of  Instance  to  the  stream,  so  they  can
                later be read with TStream.ReadComponent (337  ).  This method is intended to be used by
                an IDE, to preserve the state of a form or datamodule as designed in the IDE.

                WriteComponent simply calls WriteDescendent (338  ) with Nil ancestor.

    See also:    TStream.ReadComponent (337  ), TStream.WriteComponentRes (338  )


                                                                                 337

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.13          TStream.WriteComponentRes

    Synopsis:    Write resource header and component data to a stream

Declaration:     procedure  WriteComponentRes(const  ResName:  String;Instance:  TComponent)

    Visibility:   public

Description:     WriteComponentRes writes a ResName resource header to the stream and then calls Write-
                Component (337  ) to write the published properties of  Instance to the stream.

                This method is intened for use by an IDE that can use it to store forms or datamodules as
                designed in a Windows resource stream.

    See also:    TStream.WriteComponent (337  ), TStream.ReadComponentRes (337  )
                2.56.14          TStream.WriteDescendent

    Synopsis:    Write component data to a stream, relative to an ancestor

Declaration:     procedure  WriteDescendent(Instance:  TComponent;Ancestor:  TComponent)

    Visibility:   public

Description:     WriteDescendent writes the state of Instance to the stream where it differs from Ancestor,
                i.e.  only the changed properties are written to the stream.

                WriteDescendent creates a TWriter (374  ) object and calls its WriteDescendent (377  ) object.
                The writer is passed a binary driver object (249  ) by default.
                2.56.15          TStream.WriteDescendentRes

    Synopsis:    Write resource header and component data to a stream, relative to an ancestor

Declaration:     procedure  WriteDescendentRes(const  ResName:  String;Instance:  TComponent;
                                                              Ancestor:  TComponent)

    Visibility:   public

Description:     WriteDescendentRes  writes  a  ResName  resource  header,  and  then  calls  WriteDescendent
                (338  ) to write the state of  Instance to the stream where it differs from Ancestor, i.e.  only
                the changed properties are written to the stream.

                This method is intened for use by an IDE that can use it to store forms or datamodules as
                designed in a Windows resource stream.
                2.56.16          TStream.WriteResourceHeader

    Synopsis:    Write resource header to the stream

Declaration:     procedure  WriteResourceHeader(const  ResName:  String;
                                                                var  FixupInfo:  Integer)

    Visibility:   public

Description:     WriteResourceHeader writes a resource-file header for a resource called ResName.  It returns
                in  FixupInfo  the  argument  that  should  be  passed  on  to  TStream.FixupResourceHeader
                (339  ).

                WriteResourceHeader should not be used directly.  It is called by the TStream.WriteComponentRes
                (338  ) and TStream.WriteDescendentRes (338  ) methods.



                                                                                 338

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    See also:    TStream.FixupResourceHeader (339  ), TStream.WriteComponentRes (338  ), TStream.WriteDescendentRes
                (338  )
                2.56.17          TStream.FixupResourceHeader

    Synopsis:    Not implemented in FPC

Declaration:     procedure  FixupResourceHeader(FixupInfo:  Integer)

    Visibility:   public

Description:     FixupResourceHeader is used to write the size of the resource after a component was written
                to  stream.  The  size  is  determined  from  the  current  position,  and  it  is  written  at  position
                FixupInfo.  After that the current position is restored.

                FixupResourceHeader should never be called directly; it is handled by the streaming system.

    See also:    TStream.WriteResourceHeader (338  ), TStream.WriteComponentRes (338  ), TStream.WriteDescendentRes
                (338  )
                2.56.18          TStream.ReadResHeader

    Synopsis:    Read a resource header from the stream.

Declaration:     procedure  ReadResHeader

    Visibility:   public

Description:     ReadResourceHeader reads a reasource file header from the stream.  It positions the stream
                just beyond the header.

                ReadResourceHeader should not be called directly, it is called by the streaming system when
                needed.

       Errors:   If the resource header is invalid an EInvalidImage (215  ) exception is raised.

    See also:    TStream.ReadComponentRes (337  ), EInvalidImage (215  )
                2.56.19          TStream.ReadByte

    Synopsis:    Read a byte from the stream and return its value.

Declaration:     function  ReadByte  :  Byte

    Visibility:   public

Description:     ReadByte reads one byte from the stream and returns its value.

       Errors:   If the byte cannot be read, a EStreamError (216  ) exception will be raised.  This is a utility
                function which symply calls the Read (334  ) function.

    See also:    TStream.Read (334  ), TStream.WriteByte (340  ), TStream.ReadWord (340  ), TStream.ReadDWord
                (340  ), TStream.ReadAnsiString (340  )

                                                                                 339

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.20          TStream.ReadWord

    Synopsis:    Read a word from the stream and return its value.

Declaration:     function  ReadWord  :  Word

    Visibility:   public

Description:     ReadWord reads one Word (i.e.  2 bytes) from the stream and returns its value.  This is a
                utility function which symply calls the Read (334  ) function.

       Errors:   If the word cannot be read, a EStreamError (216  ) exception will be raised.

    See also:    TStream.Read (334  ), TStream.WriteWord (341  ), TStream.ReadByte (339  ), TStream.ReadDWord
                (340  ), TStream.ReadAnsiString (340  )
                2.56.21          TStream.ReadDWord

    Synopsis:    Read a DWord from the stream and return its value.

Declaration:     function  ReadDWord  :  Cardinal

    Visibility:   public

Description:     ReadDWord reads one DWord (i.e.  4 bytes) from the stream and returns its value.  This is a
                utility function which simply calls the Read (334  ) function.

       Errors:   If the DWord cannot be read, a EStreamError (216  ) exception will be raised.

    See also:    TStream.Read (334  ), TStream.WriteDWord (341  ), TStream.ReadByte (339  ), TStream.ReadWord
                (340  ), TStream.ReadAnsiString (340  )
                2.56.22          TStream.ReadAnsiString

    Synopsis:    Read an ansistring from the stream and return its value.

Declaration:     function  ReadAnsiString  :  String

    Visibility:   public

Description:     ReadAnsiString reads an ansistring from the stream and returns its value.  This is a utility
                function which simply calls the read function several times.  The Ansistring should be stored
                as 4 bytes (a DWord) representing the length of the string, and then the string value itself.
                The WriteAnsiString (341  ) function writes an ansistring in such a format.

       Errors:   If the AnsiString cannot be read, a EStreamError (216  ) exception will be raised.

    See also:    TStream.Read (334  ), TStream.WriteAnsiString (341  ), TStream.ReadByte (339  ), TStream.ReadWord
                (340  ), TStream.ReadDWord (340  )
                2.56.23          TStream.WriteByte

    Synopsis:    Write a byte to the stream.

Declaration:     procedure  WriteByte(b:  Byte)

    Visibility:   public


                                                                                 340

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     WriteByte  writes  the  byte  B  to  the  stream.  This  is  a  utility  function  which  simply  calls
                the Write (335  ) function.  The byte can be read from the stream using the ReadByte (339  )
                function.

       Errors:   If an error occurs when attempting to write, an EStreamError (216  ) exception will be raised.

    See also:    TStream.Write (335  ), TStream.ReadByte (339  ), TStream.WriteWord (341  ), TStream.WriteDWord
                (341  ), TStream.WriteAnsiString (341  )
                2.56.24          TStream.WriteWord

    Synopsis:    Write a word to the stream.

Declaration:     procedure  WriteWord(w:  Word)

    Visibility:   public

Description:     WriteWord writes the word W (i.e.  2 bytes) to the stream.  This is a utility function which
                simply  calls  the  Write  (335  )  function.   The  word  can  be  read  from  the  stream  using  the
                ReadWord (340  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (216  ) exception will be raised.

    See also:    TStream.Write (335  ), TStream.ReadWord (340  ), TStream.WriteByte (340  ), TStream.WriteDWord
                (341  ), TStream.WriteAnsiString (341  )
                2.56.25          TStream.WriteDWord

    Synopsis:    Write a DWord to the stream.

Declaration:     procedure  WriteDWord(d:  Cardinal)

    Visibility:   public

Description:     WriteDWord  writes  the  DWord  D  (i.e.   4  bytes)  to  the  stream.   This  is  a  utility  function
                which simply calls the Write (335  ) function.  The DWord can be read from the stream using
                the ReadDWord (340  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (216  ) exception will be raised.

    See also:    TStream.Write (335  ), TStream.ReadDWord (340  ), TStream.WriteByte (340  ), TStream.WriteWord
                (341  ), TStream.WriteAnsiString (341  )
                2.56.26          TStream.WriteAnsiString

    Synopsis:    Write an ansistring to the stream.

Declaration:     procedure  WriteAnsiString(const  S:  String)

    Visibility:   public

Description:     WriteAnsiString  writes  the  AnsiString  S  (i.e.  4  bytes)  to  the  stream.  This  is  a  utility
                function which simply calls the Write (335  ) function.  The ansistring is written as a 4 byte
                length specifier,  followed by the ansistring's content.  The ansistring can be read from the
                stream using the ReadAnsiString (340  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (216  ) exception will be raised.

    See also:    TStream.Write (335  ), TStream.ReadAnsiString (340  ), TStream.WriteByte (340  ), TStream.WriteWord
                (341  ), TStream.WriteDWord (341  )



                                                                                 341

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.56.27          TStream.Position

    Synopsis:    The current position in the stream.

Declaration:     Property  Position  :  Int64

    Visibility:   public

      Access:    Read,Write

Description:     Position can be read to determine the current position in the stream.  It can be written to
                to set the (absolute) position in the stream.  The position is zero-based, so to set the position
                at the beginning of the stream, the position must be set to zero.

 Remark:         Not all TStream descendants support setting the position in the stream, so this should be
                used with care.

       Errors:   Some descendents may raise an EStreamError (216  ) exception if they do not support setting
                the stream position.

    See also:    TStream.Size (342  ), TStream.Seek (335  )
                2.56.28          TStream.Size

    Synopsis:    The current size of the stream.

Declaration:     Property  Size  :  Int64

    Visibility:   public

      Access:    Read,Write

Description:     Size can be read to determine the stream size or to set the stream size.

 Remark:         Not all descendents of  TStream support getting or setting the stream size; they may raise
                an exception if the Size property is read or set.

    See also:    TStream.Position (342  ), TStream.Seek (335  )
                2.57          TStreamAdapter



                2.57.1         Description

                Implements IStream for TStream (333  ) descendents
                                                                                 342

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.57.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  346       Clone                  Clone the stream
                  345       Commit                 Commit data to the stream
                  345       CopyTo                 Copy data to destination stream
                  343       Create                 Create a new instance of  TStreamAdapter
                  343       Destroy                Free the TStreamAdapter instance
                  345       LockRegion             Lock a region of the stream
                  344       Read                   Read from the stream.
                  345       Revert                 Revert operations on the stream
                  344       Seek                   Set the stream position
                  344       SetSize                Set the stream size
                  346       Stat                   Return statistical data from the stream
                  346       UnlockRegion           Unlock a region of the stream
                __344_______Write__________________Write_to_the_stream_____________________________________________________________*
 *___________
                2.57.3         Property  overview

                __Page______Property_____________________Access_______Description__________________________________________________*
 *___________
                  346       Stream                       r            Stream on which adaptor works
                  347       StreamOwnership              rw           Determines what happens with the stream when the
                ______________________________________________________adaptor_is_freed_____________________________________________*
 *___________
                2.57.4         TStreamAdapter.Create

    Synopsis:    Create a new instance of  TStreamAdapter

Declaration:     constructor  Create(Stream:  TStream;Ownership:  TStreamOwnership)

    Visibility:   public

Description:     Create creates a new instance of  TStreamAdaptor.  It initializes TStreamAdapter.Stream
                (346  ) with Stream and initializes StreamOwnerShip (347  ) with Ownership.

                TStreamAdapter is an abstract class:  descendents must be created that implement the actual
                functionality.

       Errors:

    See also:    TStreamAdapter.StreamOwnerShip (347  ), TStreamAdapter.Stream (346  )
                2.57.5         TStreamAdapter.Destroy

    Synopsis:    Free the TStreamAdapter instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Explicitly  free  the  TStreamAdapter  instance.   Normally,  this  is  done  automatically  if  a
                reference to the IStream interface is freed.



                                                                                 343

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.57.6         TStreamAdapter.Read

    Synopsis:    Read from the stream.

Declaration:     function  Read(pv:  Pointer;cb:  DWORD;pcbRead:  PDWORD)  :  HResult;    Virtual

    Visibility:   public

Description:     Read implements IStream.Read (185  ) by reading from the stream specified at creation.

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Read (185  )
                2.57.7         TStreamAdapter.Write

    Synopsis:    Write to the stream

Declaration:     function  Write(pv:  Pointer;cb:  DWORD;pcbWritten:  PDWORD)  :  HResult
                                       ;    Virtual

    Visibility:   public

Description:     Write implements IStream.Write (185  ) by writing to the stream specified at creation.

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Write (185  )
                2.57.8         TStreamAdapter.Seek

    Synopsis:    Set the stream position

Declaration:     function  Seek(dlibMove:  Largeint;dwOrigin:  LongInt;
                                      out  libNewPosition:  Largeint)  :  HResult;    Virtual

    Visibility:   public

Description:     Seek implements IStream.Seek (185  ) by setting the position of the stream specified at cre-
                ation.

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Seek (185  )
                2.57.9         TStreamAdapter.SetSize

    Synopsis:    Set the stream size

Declaration:     function  SetSize(libNewSize:  Largeint)  :  HResult;    Virtual

    Visibility:   public

Description:     SetSize  implements  IStream.Setsize  (185  )  by  setting  the  size  of  the  stream  specified  at
                creation.

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Setsize (185  )
                                                                                 344

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.57.10          TStreamAdapter.CopyTo

    Synopsis:    Copy data to destination stream

Declaration:     function  CopyTo(stm:  IStream;cb:  Largeint;out  cbRead:  Largeint;
                                         out  cbWritten:  Largeint)  :  HResult;    Virtual

    Visibility:   public

Description:     CopyTo implements IStream.CopyTo (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.
                2.57.11          TStreamAdapter.Commit

    Synopsis:    Commit data to the stream

Declaration:     function  Commit(grfCommitFlags:  LongInt)  :  HResult;    Virtual

    Visibility:   public

Description:     Commit implements IStream.Commit (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Commit (185  )
                2.57.12          TStreamAdapter.Revert

    Synopsis:    Revert operations on the stream

Declaration:     function  Revert  :  HResult;    Virtual

    Visibility:   public

Description:     Revert implements IStream.Revert (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Revert (185  )
                2.57.13          TStreamAdapter.LockRegion

    Synopsis:    Lock a region of the stream

Declaration:     function  LockRegion(libOffset:  Largeint;cb:  Largeint;
                                                dwLockType:  LongInt)  :  HResult;    Virtual

    Visibility:   public

Description:     LockRegion implements IStream.LockRegion (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.LockRegion (185  )



                                                                                 345

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.57.14          TStreamAdapter.UnlockRegion

    Synopsis:    Unlock a region of the stream

Declaration:     function  UnlockRegion(libOffset:  Largeint;cb:  Largeint;
                                                   dwLockType:  LongInt)  :  HResult;    Virtual

    Visibility:   public

Description:     UnLockRegion implements IStream.UnLockRegion (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.UnLockRegion (185  )
                2.57.15          TStreamAdapter.Stat

    Synopsis:    Return statistical data from the stream

Declaration:     function  Stat(out  statstg:  TStatStg;grfStatFlag:  LongInt)  :  HResult
                                      ;    Virtual

    Visibility:   public

Description:     Stat implements IStream.Stat (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Stat (185  )
                2.57.16          TStreamAdapter.Clone

    Synopsis:    Clone the stream

Declaration:     function  Clone(out  stm:  IStream)  :  HResult;    Virtual

    Visibility:   public

Description:     Clone implements IStream.Clone (185  ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    IStream.Clone (185  )
                2.57.17          TStreamAdapter.Stream

    Synopsis:    Stream on which adaptor works

Declaration:     Property  Stream  :  TStream

    Visibility:   public

      Access:    Read

Description:     This is the stream on which the adaptor works.  It was specified at rreation.



                                                                                 346

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.57.18          TStreamAdapter.StreamOwnership

    Synopsis:    Determines what happens with the stream when the adaptor is freed

Declaration:     Property  StreamOwnership  :  TStreamOwnership

    Visibility:   public

      Access:    Read,Write

Description:     StreamOwnership determines what happens when the adaptor
                2.58          TStringList



                2.58.1         Description

                TStringList  is  a  descendent  class  of  TStrings  (351  )  that  implements  all  of  the  abstract
                methods introduced there.  It also introduces some additional methods:


                     o  Sort the list, or keep the list sorted at all times

                     o  Special handling of duplicates in sorted lists

                     o  Notification of changes in the list
                2.58.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  348       Add                  Implements the TStrings.Add (353  ) function.
                  348       Clear                Implements the TStrings.Clear (355  ) function.
                  350       CustomSort
                  348       Delete               Implements the TStrings.Delete (355  ) function.
                  347       Destroy              Destroys the stringlist.
                  348       Exchange             Implements the TStrings.Exchange (356  ) function.
                  349       Find                 Locates the index for a given string in sorted lists.
                  349       IndexOf              Overrides the TStrings.IndexOf (357  ) property.
                  349       Insert               Overrides the TStrings.Insert (358  ) method.
                __349_______Sort_________________Sorts_the_strings_in_the_list.____________________________________________________*
 *___________
                2.58.3         Property  overview

                __Page______Property_______________Access_______Description________________________________________________________*
 *___________
                  351       CaseSensitive          rw
                  350       Duplicates             rw           Describes the behaviour of a sorted list with respect to
                                                                duplicate strings.
                  351       OnChange               rw           Event triggered after the list was modified.
                  351       OnChanging             rw           Event triggered when the list is about to be modified.
                __350_______Sorted_________________rw___________Determines_whether_the_list_is_sorted_or_not.______________________*
 *___________
                2.58.4         TStringList.Destroy

    Synopsis:    Destroys the stringlist.

Declaration:     destructor  Destroy;    Override
                                                                                 347

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    Visibility:  public

Description:     Destroy clears the stringlist, release all memory allocated for the storage of the strings, and
                then calls the inherited destroy method.

 Remark:         Any objects associated to strings in the list will not  be destroyed; it is the responsability of
                the caller to destroy all objects associated with strings in the list.
                2.58.5         TStringList.Add

    Synopsis:    Implements the TStrings.Add (353  ) function.

Declaration:     function  Add(const  S:  String)  :  Integer;    Override

    Visibility:   public

Description:     Add will add S to the list.  If the list is sorted and the string S is already present in the list
                and TStringList.Duplicates (350  ) is dupError then an EStringListError (217  ) exception is
                raised.  If  Duplicates is set to dupIgnore then the return value is underfined.

                If the list is sorted, new strings will not necessarily be added to the end of the list, rather
                they will be inserted at their alphabetical position.

       Errors:   If the list is sorted and the string S is already present in the list and TStringList.Duplicates
                (350  ) is dupError then an EStringListError (217  ) exception is raised.

    See also:    TStringList.Insert (349  ), TStringList.Duplicates (350  )
                2.58.6         TStringList.Clear

    Synopsis:    Implements the TStrings.Clear (355  ) function.

Declaration:     procedure  Clear;    Override

    Visibility:   public

Description:     Implements the TStrings.Clear (355  ) function.
                2.58.7         TStringList.Delete

    Synopsis:    Implements the TStrings.Delete (355  ) function.

Declaration:     procedure  Delete(Index:  Integer);    Override

    Visibility:   public

Description:     Implements the TStrings.Delete (355  ) function.
                2.58.8         TStringList.Exchange

    Synopsis:    Implements the TStrings.Exchange (356  ) function.

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer);    Override

    Visibility:   public

Description:     Exchange will exchange two items in the list as described in TStrings.Exchange (356  ).

 Remark:         Exchange will not check whether the list os sorted or not; if  Exchange is called on a sorted
                list and the strings are not identical, the sort order of the list will be destroyed.

    See also:    TStringList.Sorted (350  ), TStrings.Exchange (356  )



                                                                                 348

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.58.9         TStringList.Find

    Synopsis:    Locates the index for a given string in sorted lists.

Declaration:     function  Find(const  S:  String;var  Index:  Integer)  :  Boolean;    Virtual

    Visibility:   public

Description:     Find  returns  True  if  the  string  S  is  present  in  the  list.  Upon  exit,  the  Index  parameter
                will contain the position of the string in the list.  If the string is not found, the function will
                return  False  and  Index  will  contain  the  position  where  the  string  will  be  inserted  if  it  is
                added to the list.

 Remark:

                     1.Use this method only on sorted lists.  For unsorted lists, use TStringList.IndexOf (349  )
                       instead.

                     2.Find uses a binary search method to locate the string
                2.58.10          TStringList.IndexOf

    Synopsis:    Overrides the TStrings.IndexOf (357  ) property.

Declaration:     function  IndexOf(const  S:  String)  :  Integer;    Override

    Visibility:   public

Description:     IndexOf  overrides  the  ancestor  method  TStrings.indexOf  (357  ).   It  tries  to  optimize  the
                search by executing a binary search if the list is sorted.  The function returns the position of
                S if it is found in the list, or -1 if the string is not found in the list.

    See also:    TStrings.IndexOf (357  ), TStringList.Find (349  )
                2.58.11          TStringList.Insert

    Synopsis:    Overrides the TStrings.Insert (358  ) method.

Declaration:     procedure  Insert(Index:  Integer;const  S:  String);    Override

    Visibility:   public

Description:     Insert  will  insert  the  string  S  at  position  Index  in  the  list.  If  the  list  is  sorted,  an  ES-
                tringListError (217  ) exception will be raised instead.  Index is a zero-based position.

       Errors:   If Index contains an invalid value (less than zero or larger than Count, or the list is sorted,
                an EStringListError (217  ) exception will be raised.

    See also:    TStringList.Add (348  ), TStrings.Insert (358  ), TStringList.InsertObject (347  )
                2.58.12          TStringList.Sort

    Synopsis:    Sorts the strings in the list.

Declaration:     procedure  Sort;    Virtual

    Visibility:   public

Description:     Sort  will  sort  the  strings  in  the  list  using  the  quicksort  algorithm.   If  the  list  has  its
                TStringList.Sorted (350  ) property set to True then nothing will be done.

    See also:    TStringList.Sorted (350  )



                                                                                 349

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.58.13          TStringList.CustomSort

    Synopsis:

Declaration:     procedure  CustomSort(CompareFn:  TStringListSortCompare);    Virtual

    Visibility:   public

Description:
                2.58.14          TStringList.Duplicates

    Synopsis:    Describes the behaviour of a sorted list with respect to duplicate strings.

Declaration:     Property  Duplicates  :  TDuplicates

    Visibility:   public

      Access:    Read,Write

Description:     Duplicates describes what to do in case a duplicate value is added to the list:



                                                                       Table 2.22:



                  dupIgnore          Duplicate values will not be be added to the list, but no error will be triggered.
                  dupError           If an attempt is made to add a duplicate value to the list, an EStringListError (217  ) except*
 *ion is raised.
                  dupAccept          Duplicate values can be added to the list.
                If the stringlist is not sorted, the Duplicates setting is ignored.
                2.58.15          TStringList.Sorted

    Synopsis:    Determines whether the list is sorted or not.

Declaration:     Property  Sorted  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Sorted  can  be  set  to  True  in  order  to  cause  the  list  of  strings  to  be  sorted.   Further
                additions to the list will be inserted at the correct position so the list remains sorted at all
                times.  Setting the property to False has no immediate effect, but will allow strings to be
                inserted at any position.

 Remark:

                     1.When  Sorted  is  True,  TStringList.Insert  (349  )  cannot  be  used.    For  sorted  lists,
                       TStringList.Add (348  ) should be used instead.

                     2.If  Sorted is True, the TStringList.Duplicates (350  ) setting has effect.  This setting is
                       ignored when Sorted is False.

    See also:    TStringList.Sort (349  ), TStringList.Duplicates (350  ), TStringList.Add (348  ), TstringList.Insert
                (349  )



                                                                                 350

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.58.16          TStringList.CaseSensitive

    Synopsis:

Declaration:     Property  CaseSensitive  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Indicates whether locating strings happens in a case sensitive manner.
                2.58.17          TStringList.OnChange

    Synopsis:    Event triggered after the list was modified.

Declaration:     Property  OnChange  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnChange can be assigned to respond to changes that have occurred in the list.  The handler
                is called whenever strings are added, moved, modified or deleted from the list.

                The Onchange event is triggered after the modification took place.  When the modification
                is about to happen, an TstringList.OnChanging (351  ) event occurs.

    See also:    TStringList.OnChanging (351  )
                2.58.18          TStringList.OnChanging

    Synopsis:    Event triggered when the list is about to be modified.

Declaration:     Property  OnChanging  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnChanging  can  be  assigned  to  respond  to  changes  that  will  occurred  in  the  list.   The
                handler is called whenever strings will be added, moved, modified or deleted from the list.

                The Onchanging event is triggered before the modification will take place.  When the modi-
                fication has happened, an TstringList.OnChange (351  ) event occurs.

    See also:    TStringList.OnChange (351  )
                2.59          TStrings



                2.59.1         Description

                TStrings implements an abstract class to manage an array of strings.  It introduces methods
                to set and retrieve strings in the array, searching for a particular string, concatenating the
                strings and so on.  It also allows an arbitrary object to be associated with each string.

                It  also  introduces  methods  to  manage  a  series  of  name=value  settings,  as  found  in  many
                configuration files.

                                                                                 351

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___
An instance of TStrings is never created directly, instead a descendent class such as TStringList
(347  ) should be created.  This is because TStrings is an abstract class which does not imple-
ment all methods; TStrings also doesn't store any strings, this is the functionality introduced
in descendents such as TStringList (347  ).
2.59.2         Method  overview

__Page______Property____________________Description___________________________________________________________________________
  353       Add                         Add a string to the list
  353       AddObject                   Add a string and associated object to the list.
  354       AddStrings                  Add contents of another stringlist to this list.
  354       Append                      Add a string to the list.
  354       Assign                      Assign the contents of another stringlist to this one.
  355       BeginUpdate                 Mark the beginning of an update batch.
  355       Clear                       Removes all strings and associated objects from the list.
  355       Delete                      Delete a string from the list.
  353       Destroy                     Frees all strings and objects, and removes the list from mem-
                                        ory.
  356       EndUpdate                   Mark the end of an update batch.
  356       Equals                      Compares the contents of two stringlists.
  356       Exchange                    Exchanges two strings in the list.
  361       ExtractName                 Extract the name part of a string
  361       GetNameValue                Return  both  name  and  value  of  a  name,value  pair  based  on
                                        it's index.
  357       GetText                     Returns the contents as a PChar
  357       IndexOf                     Find a string in the list and return its position.
  357       IndexOfName                 Finds the index of a name in the name-value pairs.
  358       IndexOfObject               Finds an object in the list and returns its index.
  358       Insert                      Insert a string in the list.
  358       InsertObject                Insert a string and associated object in the list.
  359       LoadFromFile                Load the contents of a file as a series of strings.
  359       LoadFromStream              Load the contents of a stream as a series of strings.
  359       Move                        Move a string from one place in the list to another.
  360       SaveToFile                  Save the contents of the list to a file.
  360       SaveToStream                Save the contents of the string to a stream.
__360_______SetText_____________________Set_the_contents_of_the_list_from_a_PChar.____________________________________________


                                                                 352

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.59.3         Property  overview

                __Page______Property_________________________Access_______Description______________________________________________*
 *___________
                  363       Capacity                         rw           Capacity of the list, i.e.  number of strings that
                                                                          the list can currently hold before it tries to ex-
                                                                          pand.
                  363       CommaText                        rw           Contents of the list as a comma-separated string.
                  364       Count                            r            Number of strings in the list.
                  362       DelimitedText                    rw           Get  or  set  all  strings  in  the  list  in  a  delimit*
 *ed
                                                                          form.
                  362       Delimiter                        rw           Delimiter character used in DelimitedText (362  ).
                  364       Names                            r            Name parts of the name-value pairs in the list.
                  362       NameValueSeparator               rw           Value   of   the   character   used   to   separate
                                                                          name,value pairs
                  364       Objects                          rw           Indexed access to the objects associated with the
                                                                          strings in the list.
                  362       QuoteChar                        rw           Quote character used in DelimitedText (362  ).
                  365       Strings                          rw           Indexed access to the strings in the list.
                  366       StringsAdapter                   rw           Not implemented in Free Pascal.
                  366       Text                             rw           Contents of the list as one big string.
                  361       TextLineBreakStyle               rw           Determines which line breaks to use in the Text
                                                                          (366  ) property
                  362       ValueFromIndex                   rw
                __365_______Values___________________________rw___________Value_parts_of_the_name-value_pairs_in_the_list._________*
 *___________
                2.59.4         TStrings.Destroy

    Synopsis:    Frees all strings and objects, and removes the list from memory.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy is the destructor of TStrings it does nothing except calling the inherited destruc-
                tor.
                2.59.5         TStrings.Add

    Synopsis:    Add a string to the list

Declaration:     function  Add(const  S:  String)  :  Integer;    Virtual

    Visibility:   public

Description:     Add adds S at the end of the list and returns the index of  S in the list (which should equal
                Tstrings.Count (364  )

    See also:    TStrings.Items  (351  ),  TStrings.AddObject  (353  ),  TStrings.Insert  (358  ),  TStrings.Delete
                (355  ), TStrings.Strings (365  ), TStrings.Count (364  )
                2.59.6         TStrings.AddObject

    Synopsis:    Add a string and associated object to the list.

Declaration:     function  AddObject(const  S:  String;AObject:  TObject)  :  Integer;    Virtual
                                                                                 353

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    Visibility:  public

Description:     AddObject adds S to the list of strings, and associates AObject with it.  It returns the index
                of  S.

 Remark:        An object added to the list is not automatically destroyed by the list of the list is destroyed
                or  the  string  it  is  associated  with  is  deleted.  It  is  the  responsibility  of  the  application  to
                destroy any objects associated with strings.

    See also:    TStrings.Add  (353  ),  Tstrings.Items  (351  ),  TStrings.Objects  (364  ),  Tstrings.InsertObject
                (358  )
                2.59.7         TStrings.Append

    Synopsis:    Add a string to the list.

Declaration:     procedure  Append(const  S:  String)

    Visibility:   public

Description:     Append  does  the  same  as  TStrings.Add  (353  ),  only  it  does  not  return  the  index  of  the
                inserted string.

    See also:    TStrings.Add (353  )
                2.59.8         TStrings.AddStrings

    Synopsis:    Add contents of another stringlist to this list.

Declaration:     procedure  AddStrings(TheStrings:  TStrings);    Virtual

    Visibility:   public

Description:     AddStrings adds the contents of  TheStrings to the stringlist.  Any associated objects are
                added as well.

    See also:    TStrings.Add (353  ), TStrings.Assign (354  )
                2.59.9         TStrings.Assign

    Synopsis:    Assign the contents of another stringlist to this one.

Declaration:     procedure  Assign(Source:  TPersistent);    Override

    Visibility:   public

Description:     Assign replaces the contents of the stringlist with the contents of  Source if  Source is also
                of type TStrings.  Any associated objects are copied as well.

    See also:    TStrings.Add (353  ), TStrings.AddStrings (354  ), TPersistent.Assign (318  )

                                                                                 354

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.59.10          TStrings.BeginUpdate

    Synopsis:    Mark the beginning of an update batch.

Declaration:     procedure  BeginUpdate

    Visibility:   public

Description:     BeginUpdate increases the update count by one.  It is advisable to call BeginUpdate before
                lengthy  operations  on  the  stringlist.   At  the  end  of  these  operation,  TStrings.EndUpdate
                (356  ) should be called to mark the end of the operation.  Descendent classes may use this
                information to perform optmizations.  e.g.  updating the screen only once after many strings
                were added to the list.

                All TStrings methods that modify the string list call BeginUpdate before the actual opera-
                tion, and call endUpdate when the operation is finished.  Descendent classes should also call
                these methods when modifying the string list.

 Remark:         Always put the corresponding call to TStrings.EndUpdate (356  ) in the context of a Finally
                block, to ensure that the update count is always descreased at the end of the operation, even
                if an exception occurred:


                With  MyStrings  do
                       try
                          BeginUpdate;
                          //  Some  lengthy  operation.
                       Finally
                          EndUpdate
                       end;


    See also:    TStrings.EndUpdate (356  )
                2.59.11          TStrings.Clear

    Synopsis:    Removes all strings and associated objects from the list.

Declaration:     procedure  Clear;    Virtual;    Abstract

    Visibility:   public

Description:     Clear will remove all strings and their associated objects from the list.  After a call to clear,
                TStrings.Count (364  ) is zero.

                Since  it  is  an  abstract  method,  TStrings  itself  does  not  implement  Clear.   Descendent
                classes such as TStringList (347  ) implement this method.

    See also:    TStrings.Items (351  ), TStrings.Delete (355  ), TStrings.Count (364  )
                2.59.12          TStrings.Delete

    Synopsis:    Delete a string from the list.

Declaration:     procedure  Delete(Index:  Integer);    Virtual;    Abstract

    Visibility:   public

                                                                                 355

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     Delete  deletes  the  string  at  position  Index  from  the  list.   The  associated  object  is  also
                removed from the list, but not destroyed.  Index is zero-based, and should be in the range 0
                to Count-1.

                Since  it  is  an  abstract  method,  TStrings  itself  does  not  implement  Delete.   Descendent
                classes such as TStringList (347  ) implement this method.

       Errors:   If  Index is not in the allowed range, an EStringListError (217  ) is raised.

    See also:    TStrings.Insert (358  ), TStrings.Items (351  ), TStrings.Clear (355  )
                2.59.13          TStrings.EndUpdate

    Synopsis:    Mark the end of an update batch.

Declaration:     procedure  EndUpdate

    Visibility:   public

Description:     EndUpdate should be called at the end of a lengthy operation on the stringlist, but only if
                there was a call to BeginUpdate before the operation was started.  It is best to put the call
                to  EndUpdate  in  the  context  of  a  Finally  block,  so  it  will  be  called  even  if  an  exception
                occurs.

                For more information, see TStrings.BeginUpdate (355  ).

    See also:    TStrings.BeginUpdate (355  )
                2.59.14          TStrings.Equals

    Synopsis:    Compares the contents of two stringlists.

Declaration:     function  Equals(TheStrings:  TStrings)  :  Boolean

    Visibility:   public

Description:     Equals  compares  the  contents  of  the  stringlist  with  the  contents  of  TheStrings.   If  the
                contents match, i.e.  the stringlist contain an equal amount of strings, and all strings match,
                then True is returned.  If the number of strings in the lists is is unequal, or they contain one
                or more different strings, False is returned.

 Remark:

                     1.The strings are compared case-insensitively.

                     2.The associated objects are not compared

    See also:    Tstrings.Items (351  ), TStrings.Count (364  ), TStrings.Assign (354  )
                2.59.15          TStrings.Exchange

    Synopsis:    Exchanges two strings in the list.

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer);    Virtual

    Visibility:   public

Description:     Exchange  exchanges  the  strings  at  positions  Index1  and  Index2.  The  associated  objects
                are also exchanged.

                Both indexes must be in the range of valid indexes, i.e.  must have a value between 0 and
                Count-1.



                                                                                 356

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
       Errors:   If either Index1 or Index2 is not in the range of valid indexes, an EStringListError (217  )
                exception is raised.

    See also:    TStrings.Move (359  ), TStrings.Strings (365  ), TStrings.Count (364  )
                2.59.16          TStrings.GetText

    Synopsis:    Returns the contents as a PChar

Declaration:     function  GetText  :  PChar;    Virtual

    Visibility:   public

Description:     GetText allocates a memory buffer and compies the contents of the stringlist to this buffer
                as a series of strings, separated by an end-of-line marker.  The buffer is zero terminated.

 Remark:         The caller is responsible for freeing the returned memory buffer.
                2.59.17          TStrings.IndexOf

    Synopsis:    Find a string in the list and return its position.

Declaration:     function  IndexOf(const  S:  String)  :  Integer;    Virtual

    Visibility:   public

Description:     IndexOf searches the list for S. The search is case-insensitive.  If a matching entry is found,
                its position is returned.  if no matching string is found, -1 is returned.

 Remark:

                     1.Only the first occurrence of the string is returned.

                     2.The returned position is zero-based, i.e.  0 indicates the first string in the list.

    See also:    TStrings.IndexOfObject (358  ), TStrings.IndexOfName (357  ), TStrings.Strings (365  )
                2.59.18          TStrings.IndexOfName

    Synopsis:    Finds the index of a name in the name-value pairs.

Declaration:     function  IndexOfName(const  Name:  String)  :  Integer;    Virtual

    Visibility:   public

Description:     IndexOfName searches in the list of strings for a name-value pair with name part Name.  If
                such a pair is found, it returns the index of the pair in the stringlist.  If no such pair is found,
                the function returns -1.  The search is done case-insensitive.

 Remark:

                     1.Only the first occurrence of a matching name-value pair is returned.

                     2.The returned position is zero-based, i.e.  0 indicates the first string in the list.

    See also:    TStrings.IndexOf (357  ), TStrings.IndexOfObject (358  ), TStrings.Strings (365  )



                                                                                 357

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.59.19          TStrings.IndexOfObject

    Synopsis:    Finds an object in the list and returns its index.

Declaration:     function  IndexOfObject(AObject:  TObject)  :  Integer;    Virtual

    Visibility:   public

Description:     IndexOfObject  searchs  through  the  list  of  strings  till  it  find  a  string  associated  with
                AObject, and returns the index of this string.  If no such string is found, -1 is returned.

 Remark:

                     1.Only the first occurrence of a string with associated object AObject is returned; if more
                       strings in the list can be associated with AObject, they will not be found by this routine.

                     2.The returned position is zero-based, i.e.  0 indicates the first string in the list.
                2.59.20          TStrings.Insert

    Synopsis:    Insert a string in the list.

Declaration:     procedure  Insert(Index:  Integer;const  S:  String);    Virtual;    Abstract

    Visibility:   public

Description:     Insert inserts the string S at position Index in the list.  Index is a zero-based position, and
                can have values from 0 to Count.  If  Index equals Count then the string is appended to the
                list.

 Remark:

                     1.All methods that add strings to the list use Insert to add a string to the list.

                     2.If the string has an associated object, use TStrings.InsertObject (358  ) instead.

       Errors:   If  Index is less than zero or larger than Count then an EStringListError (217  ) exception is
                raised.

    See also:    TStrings.Add (353  ), TStrings.InsertObject (358  ), TStrings.Append (354  ), TStrings.Delete
                (355  )
                2.59.21          TStrings.InsertObject

    Synopsis:    Insert a string and associated object in the list.

Declaration:     procedure  InsertObject(Index:  Integer;const  S:  String;AObject:  TObject)

    Visibility:   public

Description:     InsertObject  inserts  the  string  S  and  its  associated  objectAObject  at  position  Index  in
                the  list.   Index  is  a  zero-based  position,  and  can  have  values  from  0  to  Count.   If  Index
                equals Count then the string is appended to the list.

       Errors:   If  Index is less than zero or larger than Count then an EStringListError (217  ) exception is
                raised.

    See also:    TStrings.Insert (358  ), TStrings.AddObject (353  ), TStrings.Append (354  ), TStrings.Delete
                (355  )



                                                                                 358

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.59.22          TStrings.LoadFromFile

    Synopsis:    Load the contents of a file as a series of strings.

Declaration:     procedure  LoadFromFile(const  FileName:  String);    Virtual

    Visibility:   public

Description:     LoadFromFile loads the contents of a file into the stringlist.  Each line in the file (as marked
                by the end-of-line marker of the particular OS the application runs on) becomes one string
                in the stringlist.  This action replaces the contents of the stringlist, it does not append the
                strings to the current content.

                LoadFromFile simply creates a file stream (285  ) with the given filename, and then executes
                TStrings.LoadfromStream (359  ); after that the file stream object is destroyed again.

    See also:    TStrings.LoadFromStream (359  ), TStrings.SaveToFile (360  ), Tstrings.SaveToStream (360  )
                2.59.23          TStrings.LoadFromStream

    Synopsis:    Load the contents of a stream as a series of strings.

Declaration:     procedure  LoadFromStream(Stream:  TStream);    Virtual

    Visibility:   public

Description:     LoadFromStream loads the contents of  Stream into the stringlist.  Each line in the stream
                (as marked by the end-of-line marker of the particular OS the application runs on) becomes
                one  string  in  the  stringlist.  This  action  replaces  the  contents  of  the  stringlist,  it  does  not
                append the strings to the current content.

    See also:    TStrings.LoadFromFile (359  ), TStrings.SaveToFile (360  ), Tstrings.SaveToStream (360  )
                2.59.24          TStrings.Move

    Synopsis:    Move a string from one place in the list to another.

Declaration:     procedure  Move(CurIndex:  Integer;NewIndex:  Integer);    Virtual

    Visibility:   public

Description:     Move  moves  the  string  at  position  CurIndex  so  it  has  position  NewIndex  after  the  move
                operation.   The  object  associated  to  the  string  is  also  moved.   CurIndex  and  NewIndex
                should be in the range of  0 to Count-1.

 Remark:         NewIndex is not  the position in the stringlist before the move operation starts.  The move
                operation


                     1.removes the string from position CurIndex

                     2.inserts the string at position NewIndex


                This may not lead to the desired result if  NewIndex is bigger than CurIndex.  Consider the
                following example:


                With  MyStrings  do
                       begin
                       Clear;
                       Add('String  0');
                       Add('String  1');



                                                                                 359

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                      Add('String  2');
                      Add('String  3');
                      Add('String  4');
                      Move(1,3);
                      end;


                After the Move operation has completed, 'String 1' will be between 'String 3' and 'String 4'.

       Errors:   If either CurIndex or NewIndex is outside the allowed range, an EStringListError (217  ) is
                raised.

    See also:    TStrings.Exchange (356  )
                2.59.25          TStrings.SaveToFile

    Synopsis:    Save the contents of the list to a file.

Declaration:     procedure  SaveToFile(const  FileName:  String);    Virtual

    Visibility:   public

Description:     SaveToFile saves the contents of the stringlist to the file with name FileName.  It writes
                the strings to the file, separated by end-of-line markers, so each line in the file will contain
                1 string from the stringlist.

                SaveToFile creates a file stream (285  ) with name FileName, calls TStrings.SaveToStream
                (360  ) and then destroys the file stream object.

       Errors:   An EStreamError (216  ) exception can be raised if the file FileName cannot be opened, or
                if it cannot be written to.

    See also:    TStrings.SaveToStream (360  ), Tstrings.LoadFromStream (359  ), TStrings.LoadFromFile (359  )
                2.59.26          TStrings.SaveToStream

    Synopsis:    Save the contents of the string to a stream.

Declaration:     procedure  SaveToStream(Stream:  TStream);    Virtual

    Visibility:   public

Description:     SaveToStream  saves  the  contents  of  the  stringlist  to  Stream.  It  writes  the  strings  to  the
                stream, separated by end-of-line markers, so each 'line' in the stream will contain 1 string
                from the stringlist.

       Errors:   An EStreamError (216  ) exception can be raised if the stream cannot be written to.

    See also:    TStrings.SaveToFile (360  ), Tstrings.LoadFromStream (359  ), TStrings.LoadFromFile (359  )
                2.59.27          TStrings.SetText

    Synopsis:    Set the contents of the list from a PChar.

Declaration:     procedure  SetText(TheText:  PChar);    Virtual

    Visibility:   public


                                                                                 360

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     SetText  parses  the  contents  of  TheText  and  fills  the  stringlist  based  on  the  contents.  It
                regards TheText as a series of strings, separated by end-of-line markers.  Each of these strings
                is added to the stringlist.

    See also:    TStrings.Text (366  )
                2.59.28          TStrings.GetNameValue

    Synopsis:    Return both name and value of a name,value pair based on it's index.

Declaration:     procedure  GetNameValue(Index:  Integer;out  AName:  String;
                                                     out  AValue:  String)

    Visibility:   public

Description:     Return both name and value of a name,value pair based on it's index.
                2.59.29          TStrings.ExtractName

    Synopsis:    Extract the name part of a string

Declaration:     function  ExtractName(const  S:  String)  :  String

    Visibility:   public

Description:     ExtractName returns the name part (the part before the NameValueSeparator (362  ) charac-
                ter) of the string.  If the character is not present, an empty string is returned.  The resulting
                string is not trimmed, it can end or start with spaces.

    See also:    TStrings.NameValueSeparator (362  )
                2.59.30          TStrings.TextLineBreakStyle

    Synopsis:    Determines which line breaks to use in the Text (366  ) property

Declaration:     Property  TextLineBreakStyle  :  TTextLineBreakStyle

    Visibility:   public

      Access:    Read,Write

Description:     TextLineBreakStyle determines which linebreak style is used when constructing the Text
                property:  the same rules are used as in the writing to text files:


                tlbsLF     Lines are separated with a linefeed character #10.

                tlbsCRLF        Lines are separated with a carriage-return/linefeed character pair:  #13#10.

                tlbsCR     Lines are separated with a carriage-return character #13.


                It has no effect when setting the text property.

    See also:    #rtl.classes.TStrings.Text (366  )

                                                                                 361

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.59.31          TStrings.Delimiter

    Synopsis:    Delimiter character used in DelimitedText (362  ).

Declaration:     Property  Delimiter  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     Delimiter character used in DelimitedText (362  ).
                2.59.32          TStrings.DelimitedText

    Synopsis:    Get or set all strings in the list in a delimited form.

Declaration:     Property  DelimitedText  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Get or set all strings in the list in a delimited form.
                2.59.33          TStrings.QuoteChar

    Synopsis:    Quote character used in DelimitedText (362  ).

Declaration:     Property  QuoteChar  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     Quote character used in DelimitedText (362  ).
                2.59.34          TStrings.NameValueSeparator

    Synopsis:    Value of the character used to separate name,value pairs

Declaration:     Property  NameValueSeparator  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     Value of the character used to separate name,value pairs
                2.59.35          TStrings.ValueFromIndex

    Synopsis:

Declaration:     Property  ValueFromIndex[Index:  Integer]:  String

    Visibility:   public

      Access:    Read,Write

Description:     Return the value part of a string based on it's index.



                                                                                 362

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.59.36          TStrings.Capacity

    Synopsis:    Capacity of the list, i.e.  number of strings that the list can currently hold before it tries to
                expand.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity  is  the  number  of  strings  that  the  list  can  hold  before  it  tries  to  allocate  more
                memory.

                TStrings returns TStrings.Count (364  ) when read.  Trying to set the capacity has no effect.
                Descendent classes such as TStringlist (347  ) can override this property such that it actually
                sets the new capacity.

    See also:    TStringList (347  ), TStrings.Count (364  )
                2.59.37          TStrings.CommaText

    Synopsis:    Contents of the list as a comma-separated string.

Declaration:     Property  CommaText  :  String

    Visibility:   public

      Access:    Read,Write

Description:     CommaText  represents  the  stringlist  as  a  single  string,  consisting  of  a  comma-separated
                concatenation  of  the  strings  in  the  list.  If  one  of  the  strings  contains  spaces,  comma's  or
                quotes it will be enclosed by double quotes.  Any double quotes in a string will be doubled.
                For instance the following strings:


                Comma,string
                Quote"string
                Space  string
                NormalSttring


                is converted to


                "Comma,string","Quote""String","Space  string",NormalString


                Conversely, when setting the CommaText property, the text will be parsed according to the
                rules outlined above,  and the strings will be set accordingly.  Note that spaces will in this
                context be regarded as string separators, unless the string as a whole is contained in double
                quotes.  Spaces that occur next to a delimiter will be ignored.  The following string:


                "Comma,string"  ,  "Quote""String",Space  string,,  NormalString


                Will be converted to


                Comma,String
                Quote"String
                Space
                String


                NormalString



                                                                                 363

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                This is a special case of the DelimitedText (185  ) property where the quote character is always
                the double quote, and the delimiter is always the colon.

    See also:    TStrings.Text (366  ), TStrings.SetText (360  )
                2.59.38          TStrings.Count

    Synopsis:    Number of strings in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read

Description:     Count  is  the  current  number  of  strings  in  the  list.   TStrings  does  not  implement  this
                property; descendent classes should override the property read handler to return the correct
                value.

                Strings  in  the  list  are  always  uniquely  identified  by  their  Index;  the  index  of  a  string  is
                zero-based, i.e.  it's supported range is 0 to Count-1.  trying to access a string with an index
                larger than or equal to Count will result in an error.  Code that iterates over the list in a
                stringlist should always take into account the zero-based character of the list index.

    See also:    TStrings.Strings (365  ), TStrings.Objects (364  ), TStrings.Capacity (363  )
                2.59.39          TStrings.Names

    Synopsis:    Name parts of the name-value pairs in the list.

Declaration:     Property  Names[Index:  Integer]:  String

    Visibility:   public

      Access:    Read

Description:     Names provides indexed access to the names of the name-value pairs in the list.  It returns
                the name part of the Index-th string in the list.

 Remark:         The index is not an index based on the number of name-value pairs in the list.  It is the
                name part of the name-value pair a string Index in the list.  If the string at position Index
                is not a name-value pair (i.e.  does not contain the equal sign (=)), then an empty name is
                returned.

    See also:    TStrings.Values (365  ), TStrings.IndexOfName (357  )
                2.59.40          TStrings.Objects

    Synopsis:    Indexed access to the objects associated with the strings in the list.

Declaration:     Property  Objects[Index:  Integer]:  TObject

    Visibility:   public

      Access:    Read,Write

                                                                                 364

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     Objects provides indexed access to the objects associated to the strings in the list.  Index
                is a zero-based index and must be in the range of  0 to Count-1.

                Setting the objects property will not free the previously associated object, if there was one.
                The caller is repsonsible for freeing the object that was previously associated to the string.

                TStrings does not implement any storage for objects.  Reading the Objects property will
                always return Nil,  Setting the property will have no effect.  It is the responsability of the
                descendent classes to provide storage for the associated objects.

       Errors:   If an Index outside the valid range is specified, an EStringListError (217  ) exception will be
                raised.

    See also:    TStrings.Strings (365  ), TStrings.IndexOfObject (358  ), TStrings.Names (364  ), TStrings.Values
                (365  )
                2.59.41          TStrings.Values

    Synopsis:    Value parts of the name-value pairs in the list.

Declaration:     Property  Values[Name:  String]:  String

    Visibility:   public

      Access:    Read,Write

Description:     Values represents the value parts of the name-value pairs in the list.

                When reading this property, if there is a name-value pair in the list of strings that has name
                part Name, then the corresponding value is returned.  If there is no such pair, an empty string
                is returned.

                When  writing  this  value,  first  it  is  checked  whether  there  exists  a  name-value  pair  in  the
                list with name Name.  If such a pair is found, it's value part is overwritten with the specified
                value.  If no such pair is found, a new name-value pair is added with the specified Name and
                value.

 Remark:

                     1.Names are compared case-insensitively.

                     2.Any character, including whitespace, up till the first equal (=) sign in a string is con-
                       sidered part of the name.

    See also:    TStrings.Names (364  ), TStrings.Strings (365  ), TStrings.Objects (364  )
                2.59.42          TStrings.Strings

    Synopsis:    Indexed access to the strings in the list.

Declaration:     Property  Strings[Index:  Integer]:  String;  default

    Visibility:   public

      Access:    Read,Write

Description:     Strings is the default property of  TStrings.  It provides indexed read-write access to the
                list of strings.  Reading it will return the string at position Index in the list.  Writing it will
                set the string at position Index.


                                                                                 365

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                Index is the position of the string in the list.  It is zero-based, i.e.  valued values range from 0
                (the first string in the list) till Count-1 (the last string in the list).  When browsing through
                the strings in the list, this fact must be taken into account.

                To access the objects associated with the strings in the list, use the TStrings.Objects (364  )
                property.  The name parts of name-value pairs can be accessed with the TStrings.Names (364  )
                property, and the values can be set or read through the TStrings.Values (365  ) property.

                Searching through the list can be done using the TStrings.IndexOf (357  ) method.

       Errors:   If  Index is outside the allowed range, an EStringListError (217  ) exception is raised.

    See also:    TStrings.Count (364  ), TStrings.Objects (364  ), TStrings.Names (364  ), TStrings.Values (365  ),
                TStrings.IndexOf (357  )
                2.59.43          TStrings.Text

    Synopsis:    Contents of the list as one big string.

Declaration:     Property  Text  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Text  returns,  when  read,  the  contents  of  the  stringlist  as  one  big  string  consisting  of  all
                strings in the list, separated by an end-of-line marker.  When this property is set, the string
                will be cut into smaller strings, based on the positions of end-of-line markers in the string.
                Any previous content of the stringlist will be lost.

 Remark:         If any of the strings in the list contains an end-of-line marker, then the resulting string will
                appear  to  contain  more  strings  than  actually  present  in  the  list.  To  avoid  this  ambiguity,
                use the TStrings.CommaText (363  ) property instead.

    See also:    TStrings.Strings (365  ), TStrings.Count (364  ), TStrings.CommaText (363  )
                2.59.44          TStrings.StringsAdapter

    Synopsis:    Not implemented in Free Pascal.

Declaration:     Property  StringsAdapter  :  IStringsAdapter

    Visibility:   public

      Access:    Read,Write

Description:     Not implemented in Free Pascal.
                2.60          TStringStream



                2.60.1         Description

                TStringStream stores its data in an ansistring.  The contents of this string is available as
                the DataString (368  ) property.  It also introduces some methods to read or write parts of the
                stringstream's data as a string.

                The main purpose of a TStringSTream is to be able to treat a string as a stream from which
                can be read.
                                                                                 366

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.60.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  367       Create              Creates a new stringstream and sets its initial content.
                  367       Read                Reads from the stream.
                  367       ReadString          Reads a string of length Count
                  368       Seek                Sets the position in the stream.
                  368       Write               Write overries the TStream.Write (335  ) method.
                __368_______WriteString_________WriteString_writes_a_string_to_the_stream._________________________________________*
 *___________
                2.60.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                __368_______DataString_________r____________Contains_the_contents_of_the_stream_in_string_form_____________________*
 *___________
                2.60.4         TStringStream.Create

    Synopsis:    Creates a new stringstream and sets its initial content.

Declaration:     constructor  Create(const  AString:  String)

    Visibility:   public

Description:     Create creates a new TStringStream instance and sets its initial content to Astring.  The
                position is still 0 but the size of the stream will equal the length of the string.

    See also:    TStringStream.DataString (368  )
                2.60.5         TStringStream.Read

    Synopsis:    Reads from the stream.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the Read (334  ) from TStream (333  ).  It tries to read Count bytes into Buffer.
                It returns the number of bytes actually read.  The position of the stream is advanced with
                the number of bytes actually read; When the reading has reached the end of the DataString
                (368  ), then the reading stops, i.e.  it is not possible to read beyond the end of the datastring.

    See also:    TStream.Read (334  ), TStringStream.Write (368  ), TStringStream.DataString (368  )
                2.60.6         TStringStream.ReadString

    Synopsis:    Reads a string of length Count

Declaration:     function  ReadString(Count:  LongInt)  :  String

    Visibility:   public

Description:     ReadString reads Count bytes from the stream and returns the read bytes as a string.  If
                less  than  Count  bytes  were  available,  the  string  has  as  many  characters  as  bytes  could  be
                read.

                The ReadString method is a wrapper around the Read (367  ) method.  It does not do the
                same stringas the TStream.ReadAnsiString (340  ) method, which first reads a length integer
                to determine the length of the string to be read.



                                                                                 367

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
    See also:    TStringStream.Read (367  ), TStream.ReadAnsiString (340  )
                2.60.7         TStringStream.Seek

    Synopsis:    Sets the position in the stream.

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek implements the abstract Seek (335  ) method.
                2.60.8         TStringStream.Write

    Synopsis:    Write overries the TStream.Write (335  ) method.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overries the TStream.Write (335  ) method.
                2.60.9         TStringStream.WriteString

    Synopsis:    WriteString writes a string to the stream.

Declaration:     procedure  WriteString(const  AString:  String)

    Visibility:   public

Description:     WriteString writes a string to the stream.
                2.60.10          TStringStream.DataString

    Synopsis:    Contains the contents of the stream in string form

Declaration:     Property  DataString  :  String

    Visibility:   public

      Access:    Read

Description:     Contains the contents of the stream in string form
                2.61          TTextOb jectWriter



                2.61.1         Description

                Not yet implemented.


                                                                                 368

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.62          TThread



                2.62.1         Description

                The TThread class encapsulates the native thread support of the operating system.  To create
                a thread, declare a descendent of the TThread object and override the Execute (369  ) method.
                In this method, the tthread's code should be executed.  To run a thread, create an instance
                of the tthread descendent, and call it's execute method.
                2.62.2         Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  370       AfterConstruction            Code to be executed after construction but before execute.
                  369       Create                       Creates a new thread.
                  369       Destroy                      Destroys the thread object.
                  370       Resume                       Resumes the thread's execution.
                  370       Suspend                      Suspends the thread's execution.
                  370       Terminate                    Signals the thread it should terminate.
                __370_______WaitFor______________________Waits_for_the_thread_to_terminate_and_returns_the_exit_status.____________*
 *___________
                2.62.3         Property  overview

                __Page______Property____________________Access_______Description___________________________________________________*
 *___________
                  372       FatalException              r            Exception that occured during thread execution
                  370       FreeOnTerminate             rw           Indicates whether the thread should free itself when
                                                                     it stops executing.
                  371       Handle                      r            Returns the thread handle.
                  371       OnTerminate                 rw           Event called when the thread terminates.
                  371       Priority                    rw           Returns the thread priority.
                  371       Suspended                   rw           Indicates whether the thread is suspended.
                __371_______ThreadID____________________r____________Returns_the_thread_ID.________________________________________*
 *___________
                2.62.4         TThread.Create

    Synopsis:    Creates a new thread.

Declaration:     constructor  Create(CreateSuspended:  Boolean;const  StackSize:  SizeUInt)

    Visibility:   public

Description:     Creates a new thread.
                2.62.5         TThread.Destroy

    Synopsis:    Destroys the thread object.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the thread object.

                                                                                 369

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.62.6         TThread.AfterConstruction

    Synopsis:    Code to be executed after construction but before execute.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction is overridden in TThread but currently does not do anything useful.
                2.62.7         TThread.Resume

    Synopsis:    Resumes the thread's execution.

Declaration:     procedure  Resume

    Visibility:   public

Description:     Resumes the thread's execution.
                2.62.8         TThread.Suspend

    Synopsis:    Suspends the thread's execution.

Declaration:     procedure  Suspend

    Visibility:   public

Description:     Suspends the thread's execution.
                2.62.9         TThread.Terminate

    Synopsis:    Signals the thread it should terminate.

Declaration:     procedure  Terminate

    Visibility:   public

Description:     Signals the thread it should terminate.
                2.62.10          TThread.WaitFor

    Synopsis:    Waits for the thread to terminate and returns the exit status.

Declaration:     function  WaitFor  :  Integer

    Visibility:   public

Description:     Waits for the thread to terminate and returns the exit status.
                2.62.11          TThread.FreeOnTerminate

    Synopsis:    Indicates whether the thread should free itself when it stops executing.

Declaration:     Property  FreeOnTerminate  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Indicates whether the thread should free itself when it stops executing.



                                                                                 370

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.62.12          TThread.Handle

    Synopsis:    Returns the thread handle.

Declaration:     Property  Handle  :  TThreadID

    Visibility:   public

      Access:    Read

Description:     Returns the thread handle.
                2.62.13          TThread.Priority

    Synopsis:    Returns the thread priority.

Declaration:     Property  Priority  :  TThreadPriority

    Visibility:   public

      Access:    Read,Write

Description:     Returns the thread priority.
                2.62.14          TThread.Suspended

    Synopsis:    Indicates whether the thread is suspended.

Declaration:     Property  Suspended  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Indicates whether the thread is suspended.
                2.62.15          TThread.ThreadID

    Synopsis:    Returns the thread ID.

Declaration:     Property  ThreadID  :  TThreadID

    Visibility:   public

      Access:    Read

Description:     Returns the thread ID.
                2.62.16          TThread.OnTerminate

    Synopsis:    Event called when the thread terminates.

Declaration:     Property  OnTerminate  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write

Description:     Event called when the thread terminates.



                                                                                 371

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.62.17          TThread.FatalException

    Synopsis:    Exception that occured during thread execution

Declaration:     Property  FatalException  :  TObject

    Visibility:   public

      Access:    Read

Description:     FatalException contains the exception that occurred during the thread's execution.
                2.63          TThreadList



                2.63.1         Description

                This class is not yet implemented in Free Pascal.
                2.63.2         Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  373       Add                Adds an element to the list.
                  373       Clear              Removes all emements from the list.
                  372       Create             Creates a new thread-safe list.
                  372       Destroy            Destroys the list instance.
                  373       LockList           Locks the list for exclusive access.
                  373       Remove             Removes an item from the list.
                __373_______UnlockList_________Unlocks_the_list_after_it_was_locked._______________________________________________*
 *___________
                2.63.3         Property  overview

                __Page______Property___________Access______Description_____________________________________________________________*
 *___________
                __374_______Duplicates_________rw__________Describes_what_to_do_with_duplicates____________________________________*
 *___________
                2.63.4         TThreadList.Create

    Synopsis:    Creates a new thread-safe list.

Declaration:     constructor  Create

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:
                2.63.5         TThreadList.Destroy

    Synopsis:    Destroys the list instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:



                                                                                 372

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.63.6         TThreadList.Add

    Synopsis:    Adds an element to the list.

Declaration:     procedure  Add(Item:  Pointer)

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:
                2.63.7         TThreadList.Clear

    Synopsis:    Removes all emements from the list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:
                2.63.8         TThreadList.LockList

    Synopsis:    Locks the list for exclusive access.

Declaration:     function  LockList  :  TList

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:
                2.63.9         TThreadList.Remove

    Synopsis:    Removes an item from the list.

Declaration:     procedure  Remove(Item:  Pointer)

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:
                2.63.10          TThreadList.UnlockList

    Synopsis:    Unlocks the list after it was locked.

Declaration:     procedure  UnlockList

    Visibility:   public

Description:     This class is not yet implemented in Free Pascal.

       Errors:



                                                                                 373

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.63.11          TThreadList.Duplicates

    Synopsis:    Describes what to do with duplicates

Declaration:     Property  Duplicates  :  TDuplicates

    Visibility:   public

      Access:    Read,Write

Description:     Duplicates describes what the threadlist should do when a duplicate pointer is added to
                the list.  It is identical in behaviour to the Duplicates (350  ) property of TStringList (347  ).

    See also:    TDuplicates (190  )
                2.64          TWriter



                2.64.1         Description

                Object to write component data to an arbitrary format.
                2.64.2         Method  overview

                __Page______Property___________________________Description_________________________________________________________*
 *___________
                  375       Create                             Creates a new Writer with a stream and bufsize.
                  375       DefineBinaryProperty               Callback used when defining and streaming custom prop-
                                                               erties.
                  375       DefineProperty                     Callback used when defining and streaming custom prop-
                                                               erties.
                  375       Destroy                            Destroys the writer instance.
                  376       Write                              Write raw data to stream
                  376       WriteBoolean                       Write boolean value to the stream.
                  376       WriteChar                          Write a character to the stream.
                  376       WriteCollection                    Write a collection to the stream.
                  376       WriteComponent                     Stream a component to the stream.
                  377       WriteCurrency                      Write a currency value to the stream
                  378       WriteDate                          Write a date to the stream.
                  377       WriteDescendent                    Write a descendent component to the stream.
                  377       WriteFloat                         Write a float to the stream.
                  378       WriteIdent                         Write an identifier to the stream.
                  378       WriteInteger                       Write an integer to the stream.
                  378       WriteListBegin                     Write a start-of-list marker to the stream.
                  378       WriteListEnd                       Write an end-of-list marker to the stream.
                  378       WriteRootComponent                 Write a root component to the stream.
                  377       WriteSingle                        Write a single-type real to the stream.
                  379       WriteString                        Write a string to the stream.
                  377       WriteWideChar                      Write widechar to stream
                __379_______WriteWideString____________________Write_a_widestring_value_to_the_stream______________________________*
 *___________



                                                                                 374

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.64.3         Property  overview

                __Page______Property_______________________________Access_______Description________________________________________*
 *___________
                  380       Driver                                 r            Driver used when writing to the stream.
                  379       OnFindAncestor                         rw           Event  occurring  when  an  ancestor  compo-
                                                                                nent must be found.
                  379       OnWriteMethodProperty                  rw           Handler from writing method properties.
                  380       OnWriteStringProperty                  rw           Event handler for translating strings written
                                                                                to stream.
                  380       PropertyPath                           r            Path to the property that is currently being
                                                                                written
                __379_______RootAncestor___________________________rw___________Ancestor_of_root_component.________________________*
 *___________
                2.64.4         TWriter.Create

    Synopsis:    Creates a new Writer with a stream and bufsize.

Declaration:     constructor  Create(ADriver:  TAbstractObjectWriter)
                constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Creates a new Writer with a stream and bufsize.
                2.64.5         TWriter.Destroy

    Synopsis:    Destroys the writer instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the writer instance.
                2.64.6         TWriter.DefineProperty

    Synopsis:    Callback used when defining and streaming custom properties.

Declaration:     procedure  DefineProperty(const  Name:  String;ReadData:  TReaderProc;
                                                        AWriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Override

    Visibility:   public

Description:     Callback used when defining and streaming custom properties.
                2.64.7         TWriter.DefineBinaryProperty

    Synopsis:    Callback used when defining and streaming custom properties.

Declaration:     procedure  DefineBinaryProperty(const  Name:  String;ReadData:  TStreamProc;
                                                                  AWriteData:  TStreamProc;HasData:  Boolean)
                                                                  ;    Override

    Visibility:   public

Description:     Callback used when defining and streaming custom properties.



                                                                                 375

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.64.8         TWriter.Write

    Synopsis:    Write raw data to stream

Declaration:     procedure  Write(const  Buffer;Count:  LongInt);    Virtual

    Visibility:   public

Description:     Write is introduced for Delphi compatibility to write raw data to the component stream.
                This should not be used in new production code as it will totally mess up the streaming.

    See also:    TBinaryObjectWriter.Write (251  ), TAbstractObjectWriter.Write (235  )
                2.64.9         TWriter.WriteBoolean

    Synopsis:    Write boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean)

    Visibility:   public

Description:     Write boolean value to the stream.
                2.64.10          TWriter.WriteCollection

    Synopsis:    Write a collection to the stream.

Declaration:     procedure  WriteCollection(Value:  TCollection)

    Visibility:   public

Description:     Write a collection to the stream.
                2.64.11          TWriter.WriteComponent

    Synopsis:    Stream a component to the stream.

Declaration:     procedure  WriteComponent(Component:  TComponent)

    Visibility:   public

Description:     Stream a component to the stream.
                2.64.12          TWriter.WriteChar

    Synopsis:    Write a character to the stream.

Declaration:     procedure  WriteChar(Value:  Char)

    Visibility:   public

Description:     Write a character to the stream.

                                                                                 376

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.64.13          TWriter.WriteWideChar

    Synopsis:    Write widechar to stream

Declaration:     procedure  WriteWideChar(Value:  WideChar)

    Visibility:   public

Description:     WriteWideChar writes a widechar to the stream.  This actually writes a widestring of length
                1.

    See also:    TReader.ReadWideChar (324  ), TWriter.WriteWideString (379  )
                2.64.14          TWriter.WriteDescendent

    Synopsis:    Write a descendent component to the stream.

Declaration:     procedure  WriteDescendent(ARoot:  TComponent;AAncestor:  TComponent)

    Visibility:   public

Description:     Write a descendent component to the stream.
                2.64.15          TWriter.WriteFloat

    Synopsis:    Write a float to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended)

    Visibility:   public

Description:     Write a float to the stream.
                2.64.16          TWriter.WriteSingle

    Synopsis:    Write a single-type real to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single)

    Visibility:   public

Description:     Write a single-type real to the stream.
                2.64.17          TWriter.WriteCurrency

    Synopsis:    Write a currency value to the stream

Declaration:     procedure  WriteCurrency(const  Value:  Currency)

    Visibility:   public

Description:     WriteCurrency  writes  a  currency  typed  value  to  the  stream.  This  method  does  nothing
                except call the driver method of the driver being used.

    See also:    TReader.ReadCurrency (325  )

                                                                                 377

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.64.18          TWriter.WriteDate

    Synopsis:    Write a date to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime)

    Visibility:   public

Description:     Write a date to the stream.
                2.64.19          TWriter.WriteIdent

    Synopsis:    Write an identifier to the stream.

Declaration:     procedure  WriteIdent(const  Ident:  String)

    Visibility:   public

Description:     Write an identifier to the stream.
                2.64.20          TWriter.WriteInteger

    Synopsis:    Write an integer to the stream.

Declaration:     procedure  WriteInteger(Value:  LongInt);    Overload
                procedure  WriteInteger(Value:  Int64);    Overload

    Visibility:   public

Description:     Write an integer to the stream.
                2.64.21          TWriter.WriteListBegin

    Synopsis:    Write a start-of-list marker to the stream.

Declaration:     procedure  WriteListBegin

    Visibility:   public

Description:     Write a start-of-list marker to the stream.
                2.64.22          TWriter.WriteListEnd

    Synopsis:    Write an end-of-list marker to the stream.

Declaration:     procedure  WriteListEnd

    Visibility:   public

Description:     Write an end-of-list marker to the stream.
                2.64.23          TWriter.WriteRootComponent

    Synopsis:    Write a root component to the stream.

Declaration:     procedure  WriteRootComponent(ARoot:  TComponent)

    Visibility:   public

Description:     Write a root component to the stream.



                                                                                 378

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
                2.64.24          TWriter.WriteString

    Synopsis:    Write a string to the stream.

Declaration:     procedure  WriteString(const  Value:  String)

    Visibility:   public

Description:     Write a string to the stream.
                2.64.25          TWriter.WriteWideString

    Synopsis:    Write a widestring value to the stream

Declaration:     procedure  WriteWideString(const  Value:  WideString)

    Visibility:   public

Description:     WriteWidestring writes a currency typed value to the stream.  This method does nothing
                except call the driver method of the driver being used.

    See also:    TReader.ReadWideString (327  )
                2.64.26          TWriter.RootAncestor

    Synopsis:    Ancestor of root component.

Declaration:     Property  RootAncestor  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     Ancestor of root component.
                2.64.27          TWriter.OnFindAncestor

    Synopsis:    Event occurring when an ancestor component must be found.

Declaration:     Property  OnFindAncestor  :  TFindAncestorEvent

    Visibility:   public

      Access:    Read,Write

Description:     Event occurring when an ancestor component must be found.
                2.64.28          TWriter.OnWriteMethodProperty

    Synopsis:    Handler from writing method properties.

Declaration:     Property  OnWriteMethodProperty  :  TWriteMethodPropertyEvent

    Visibility:   public

      Access:    Read,Write
                                                                                 379

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________
Description:     OnWriteMethodProperty can be set by an IDE or some streaming mechanism which handles
                dummy values for method properties; It can be used to write a real value to the stream which
                will be interpreted correctly when the stream is read.  See TWriteMethodPropertyEvent (198  )
                for a description of the arguments.

    See also:    TWriteMethodPropertyEvent (198  ), TReader.OnSetMethodProperty (329  )
                2.64.29          TWriter.OnWriteStringProperty

    Synopsis:    Event handler for translating strings written to stream.

Declaration:     Property  OnWriteStringProperty  :  TReadWriteStringPropertyEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnWriteStringProperty is called whenever a string property is written to the stream.  It
                can  be  used  e.g.   by  a  translation  mechanism  to  translate  the  strings  on  the  fly,  when  a
                form is written.  See TReadWriteStringPropertyEvent (195  ) for a description of the various
                parameters.

    See also:    TReader.OnPropertyNotFound (328  ), TReader.OnSetMethodProperty (329  ), TReadWriteString-
                PropertyEvent (195  )
                2.64.30          TWriter.Driver

    Synopsis:    Driver used when writing to the stream.

Declaration:     Property  Driver  :  TAbstractObjectWriter

    Visibility:   public

      Access:    Read

Description:     Driver used when writing to the stream.
                2.64.31          TWriter.PropertyPath

    Synopsis:    Path to the property that is currently being written

Declaration:     Property  PropertyPath  :  String

    Visibility:   public

      Access:    Read

Description:     PropertyPath is set to the property name of the class currently being written to stream.
                This is only done when TPersistent (318  ) descendent class properties are written.

                                                                                 380


Chapter   3


Reference   for   unit   'Crt'
3.1         Overview


This chapter describes the CRT unit for Free Pascal, both under dos linux and Windows.  The
unit was first written for dos by Florian klaempfl.  The unit was ported to linux by Mark May
and enhanced by Michael 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 and earlier of the
compiler) the crt unit automatically cleared the screen at program startup.

There are some caveats when using the CRT unit:


     o  Programs using the CRT unit will not be usable when input/output is being redirected
        on the command-line.

     o  For similar reasons they are not usable as CGI-scripts for use with a webserver.

     o  The use of the CRT unit and the graph unit may not always be supported.

     o  On linux or other unix OSes , executing other programs that expect special terminal
        behaviour  (using  one  of  the  special  functions  in  the  linux  unit)  will  not  work.   The
        terminal is set in RAW mode, which will destroy most terminal emulation settings.
3.2         Constants,  types  and  variables



3.2.1        Constants

Black  =  0


Black color attribute


Blink  =  128


Blink attribute


Blue  =  1


Blue color attribute



                                                             381

__________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________________________*
 *___
Brown  =  6


Brown color attribute


BW40  =  0


40 columns black and white screen mode.


BW80  =  2


80 columns black and white screen mode.


C40  =  CO40


40 columns color screen mode.


C80  =  CO80


80 columns color screen mode.


CO40  =  1


40 columns color screen mode.


CO80  =  3


80 columns color screen mode.


ConsoleMaxX  =  1024
ConsoleMaxY  =  1024
Cyan  =  3


Cyan color attribute


DarkGray  =  8


Dark gray color attribute


Flushing  =  false
Font8x8  =  256


Internal ROM font mode


Green  =  2


Green color attribute



                                                                 382

__________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________________________*
 *___
LightBlue  =  9


Light Blue color attribute


LightCyan  =  11


Light cyan color attribute


LightGray  =  7


Light gray color attribute


LightGreen  =  10


Light green color attribute


LightMagenta  =  13


Light magenta color attribute


LightRed  =  12


Light red color attribute


Magenta  =  5


Magenta color attribute


Mono  =  7


Monochrome screen mode (hercules screens)


Red  =  4


Red color attribute


ScreenHeight  :  LongInt  =  25


Current screen height.


ScreenWidth  :  LongInt  =  80


Current screen width


White  =  15


White color attribute


Yellow  =  14


Yellow color attribute



                                                                 383

__________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________________________*
 *___
3.2.2        Types

PConsoleBuf  =  ^TConsoleBuf
TCharAttr  =  packed  record
    ch  :  Char;
    attr  :  Byte;
end

TConsoleBuf  =  Array[0..ConsoleMaxX*ConsoleMaxY-1]  of  TCharAttr

3.2.3        Variables

CheckBreak  :  Boolean


Check for CTRL-Break keystroke.  Not used.


CheckEOF  :  Boolean


Check for EOF on standard input.  Not used.


CheckSnow  :  Boolean


Check snow on CGA screens.  Not used.


ConsoleBuf  :  PConsoleBuf
DirectVideo  :  Boolean


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.


LastMode  :  Word  =  3


The Lastmode variable tells you which mode was last selected for the screen.  It is defined
on DOS only.


TextAttr  :  Byte  =  $07


The TextAttr variable controls the attributes with which characters are written to screen.


WindMax  :  Word  =  $184f


The upper byte of  WindMax contains the Y coordinate while the lower byte contains the X
coordinate.  The use of this variable is deprecated, use WindMaxX and WindMaxY instead.


WindMaxX  :  DWord



                                                                 384

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                X coordinate of lower right corner of the defined window


                WindMaxY  :  DWord


                Y coordinate of lower right corner of the defined window


                WindMin  :  Word  =  $0


                The upper byte of  WindMin contains the Y coordinate while the lower byte contains the X
                coordinate.  The use of this variable is deprecated, use WindMinX and WindMinY instead.


                WindMinX  :  DWord


                X coordinate of upper left corner of the defined window


                WindMinY  :  DWord


                Y coordinate of upper left corner of the defined window
                3.3         Procedures  and  functions



                3.3.1        AssignCrt

    Synopsis:    Assign file to CRT.

Declaration:     procedure  AssignCrt(var  F:  Text)

    Visibility:   default

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.

    See also:    Window (396  )


                Listing:  ./crtex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;
                 u s e s C r t ;


                {   Program       t o  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   :  T e x t;
                 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 t o  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 t o  t h e  A s s i g n e d F i l e' ) ;
                    C l o s e(F ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                 385

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                3.3.2        ClrEol

    Synopsis:    Clear from cursor position till end of line.

Declaration:     procedure  ClrEol

    Visibility:   default

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 (388  ), InsLine (390  ), ClrScr (386  )


                Listing:  ./crtex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;
                 u s e s C r t ;


                {   Program       t o  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.  }
                 v a r
                    I ,J   :   i n t e g e r;


                 b e g i n
                    For    I : = 1  t o  1 5  do
                       For    J : = 1  t o  8 0  do
                           b e g i n
                           g o t o x y(j , i ) ;
                           Write    ( j  mod    1 0 ) ;
                           end  ;
                    Window     ( 5 , 5 , 7 5 , 1 2 ) ;
                    Write    ( 'T h i s  l i n e  w i l l be    c l e a r e d f r o m' ,
                               '  h e r e  t i l l t h e   r i g h t o f  t h e  window     ') ;
                    GotoXY     ( 2 7 ,WhereY    ) ;
                    ReadKey     ;
                    C l r E o l;
                    WriteLn     ;
                end___.____________________________________________________________________________________________________________*
 *___________

                3.3.3        ClrScr

    Synopsis:    Clear current window.

Declaration:     procedure  ClrScr

    Visibility:   default

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 (396  )


                Listing:  ./crtex/ex8.pp



                                                                                 386

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;
                 u s e s C r t ;


                {   Program       t o  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    k e y  t o   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___.____________________________________________________________________________________________________________*
 *___________

                3.3.4        cursorbig

    Synopsis:    Show big cursor

Declaration:     procedure  cursorbig

    Visibility:   default

Description:     CursorBig makes the cursor a big rectangle.  Not implemented on unixes.

       Errors:   None.

    See also:    CursorOn (387  ), CursorOff (387  )
                3.3.5        cursoroff

    Synopsis:    Hide cursor

Declaration:     procedure  cursoroff

    Visibility:   default

Description:     CursorOff switches the cursor off (i.e.  the cursor is no longer visible).  Not implemented
                on unixes.

       Errors:   None.

    See also:    CursorOn (387  ), CursorBig (387  )
                3.3.6        cursoron

    Synopsis:    Display cursor

Declaration:     procedure  cursoron

    Visibility:   default

Description:     CursorOn switches the cursor on.  Not implemented on unixes.

       Errors:   None.

    See also:    CursorBig (387  ), CursorOff (387  )
                                                                                 387

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                3.3.7        Delay

    Synopsis:    Delay program execution.

Declaration:     procedure  Delay(MS:  Word)

    Visibility:   default

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 (393  ), NoSound (392  )


                Listing:  ./crtex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;
                 u s e s C r t ;


                {   Program       t o  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 gDown    ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                3.3.8        DelLine

    Synopsis:    Delete line at cursor position.

Declaration:     procedure  DelLine

    Visibility:   default

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 (386  ), InsLine (390  ), ClrScr (386  )


                Listing:  ./crtex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;
                 u s e s C r t ;


                {   Program       t o  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  ') ;



                                                                                 388

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                    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  2   i 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___.____________________________________________________________________________________________________________*
 *___________

                3.3.9        GotoXY

    Synopsis:    Set cursor position on screen.

Declaration:     procedure  GotoXY(X:  Byte;Y:  Byte)

    Visibility:   default

Description:     GotoXY 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.

       Errors:   None.

    See also:    WhereX (395  ), WhereY (395  ), Window (396  )


                Listing:  ./crtex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;
                 u s e s C r t ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                3.3.10         HighVideo

    Synopsis:    Switch to highlighted text mode

Declaration:     procedure  HighVideo

    Visibility:   default

Description:     HighVideo  switches  the  output  to  highlighted  text.  (It  sets  the  high  intensity  bit  of  the
                video attribute)

       Errors:   None.
                                                                                 389

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
    See also:    TextColor (394  ), TextBackground (393  ), LowVideo (391  ), NormVideo (391  )


                Listing:  ./crtex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;
                 u s e s C r t ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                3.3.11         InsLine

    Synopsis:    Insert an empty line at cursor position

Declaration:     procedure  InsLine

    Visibility:   default

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.

    See also:    ClrEol (386  ), DelLine (388  ), ClrScr (386  )


                Listing:  ./crtex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;
                 u s e s C r t ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                 390

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                3.3.12         KeyPressed

    Synopsis:    Check if there is a keypress in the keybuffer

Declaration:     function  KeyPressed  :  Boolean

    Visibility:   default

Description:     Keypressed 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 (392  )


                Listing:__./crtex/ex2.pp___________________________________________________________________________________________*
 *___________

                Program       Example2       ;
                 u s e s C r t ;


                {   Program       t o  d e m o n s t r a t et h e  K e y P r e s s e df 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   k e y  i s  p r e s s e d') ;
                    r e p e a t
                    u n t i l KeyPressed        ;
                  {   The    k e y  i s  n o t  Read   ,
                      s o  i t  s h o u l d  a l s o be   o u t p u t t e d a t  t h e  c o m m a n d l i n}e
                end___.____________________________________________________________________________________________________________*
 *___________

                3.3.13         LowVideo

    Synopsis:    Switch to low intensity colors.

Declaration:     procedure  LowVideo

    Visibility:   default

Description:     LowVideo switches the output to non-highlighted text.  (It clears the high intensity bit of
                the video attribute)

                For an example, see HighVideo (389  )

       Errors:   None.

    See also:    TextColor (394  ), TextBackground (393  ), HighVideo (389  ), NormVideo (391  )
                3.3.14         NormVideo

    Synopsis:    Return to normal (startup) modus

Declaration:     procedure  NormVideo

    Visibility:   default

Description:     NormVideo switches the output to the defaults, read at startup.  (The defaults are read from
                the cursor position at startup)

                For an example, see HighVideo (389  )



                                                                                 391

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
       Errors:   None.

    See also:    TextColor (394  ), TextBackground (393  ), LowVideo (391  ), HighVideo (389  )
                3.3.15         NoSound

    Synopsis:    Stop system speaker

Declaration:     procedure  NoSound

    Visibility:   default

Description:     NoSound stops the speaker sound.  This call is not supported on all operating systems.

       Errors:   None.

    See also:    Sound (393  )


                Listing:  ./crtex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;
                 u s e s C r t ;


                {   Program       t o  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 f r o m  y o u r  s p e a k e r') ;
                    w h i l e ( i < 1 5 0 0 0 ) 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      ;  {S t o p  n o i s e}
                end___.____________________________________________________________________________________________________________*
 *___________

                3.3.16         ReadKey

    Synopsis:    Read key from keybuffer

Declaration:     function  ReadKey  :  Char

    Visibility:   default

Description:     ReadKey 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.

                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 (391  )

                                                                                 392

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                Listing:  ./crtex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;
                 u s e s C r t ;


                {   Program       t o  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 t/ R i g h t,  E s c= Q u i t' ) ;
                    r e p e a t
                       ch  := ReadKey      ;
                        c a s e ch   o f
                         # 0  :   b e g i n
                                     ch  := ReadKey      ;  { Read     ScanCode     }
                                     c a s e  ch   o f
                                       # 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     {E s c }
                end___.____________________________________________________________________________________________________________*
 *___________

                3.3.17         Sound

    Synopsis:    Sound system speaker

Declaration:     procedure  Sound(Hz:  Word)

    Visibility:   default

Description:     Sound sounds the speaker at a frequency of  hz.  Under Windows, a system sound is played
                and the frequency parameter is ignored.  On other operating systems, this routine may not
                be implemented.

       Errors:   None.

    See also:    NoSound (392  )
                3.3.18         TextBackground

    Synopsis:    Set text background

Declaration:     procedure  TextBackground(Color:  Byte)

    Visibility:   default

Description:     TextBackground  sets  the  background  color  to  CL.  CL  can  be  one  of  the  predefined  color
                constants.

       Errors:   None.

    See also:    TextColor (394  ), HighVideo (389  ), LowVideo (391  ), NormVideo (391  )


                Listing:  ./crtex/ex13.pp



                                                                                 393

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;
                 u s e s C r t ;


                {   Program       t o  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 tb 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(dG r e e n) ;
                    WriteLn     ( ' T h i s  i s  w r i t t e n i n  w i t h a   G r e e n  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___.____________________________________________________________________________________________________________*
 *___________

                3.3.19         TextColor

    Synopsis:    Set text color

Declaration:     procedure  TextColor(Color:  Byte)

    Visibility:   default

Description:     TextColor sets the foreground color to CL. CL can be one of the predefined color constants.

       Errors:   None.

    See also:    TextBackground (393  ), HighVideo (389  ), LowVideo (391  ), NormVideo (391  )


                Listing:  ./crtex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;
                 u s e s C r t ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                3.3.20         TextMode

    Synopsis:    Set screen mode.

Declaration:     procedure  TextMode(Mode:  Word)

    Visibility:   default


                                                                                 394

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
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 (396  )
                3.3.21         WhereX

    Synopsis:    Return X (horizontal) cursor position

Declaration:     function  WhereX  :  Byte

    Visibility:   default

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 (389  ), WhereY (395  ), Window (396  )


                Listing:__./crtex/ex7.pp___________________________________________________________________________________________*
 *___________

                Program       Example7       ;
                 u s e s C r t ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                3.3.22         WhereY

    Synopsis:    Return Y (vertical) cursor position

Declaration:     function  WhereY  :  Byte

    Visibility:   default

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 (389  ), WhereX (395  ), Window (396  )


                Listing:__./crtex/ex7.pp___________________________________________________________________________________________*
 *___________

                Program       Example7       ;
                 u s e s C r t ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                 395

                __________________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________
                3.3.23         Window

    Synopsis:    Create new window on screen.

Declaration:     procedure  Window(X1:  Byte;Y1:  Byte;X2:  Byte;Y2:  Byte)

    Visibility:   default

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 (389  ), WhereX (395  ), WhereY (395  ), ClrScr (386  )


                Listing:  ./crtex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;
                 u s e s C r t ;


                {   Program       t o  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 ga   window      f r o m  3 0 , 1 0 t 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    '+
                                  ' c a n' '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    k e y  t o  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    k e y  t o  r e s t o r e t o  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                 396


Chapter   4


Reference   for   unit   'dateutils'
4.1         Used  units
                                    Table 4.1:  Used units by unit 'dateutils'


                                                   __Name__________Page_____
                                                     math            688
                                                     sysutils      1356
                                                     Types           397



4.2         Overview


DateUtils  contains  a  large  number  of  date/time  manipulation  routines,  all  based  on  the
TDateTime type.  There are routines for date/time math, for comparing dates and times, for
composing dates and decomposing dates in their constituent parts.
4.3         Constants,  types  and  variables



4.3.1        Constants

ApproxDaysPerMonth  :  Double  =  30.4375


Average number of days in a month, measured over a year.  Used in MonthsBetween (443  ).


ApproxDaysPerYear  :  Double  =  365.25


Average number of days in a year, measured over 4 years.  Used in YearsBetween (484  ).


DayFriday  =  5


ISO day number for Friday


DayMonday  =  1



                                                             397

______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________________________*
 *___
ISO day number for Monday


DaySaturday  =  6


ISO day number for Saturday


DaysPerWeek  =  7


Number of days in a week.


DaysPerYear  :  Array[Boolean]  of  Word  =  (365,366  )


Array with number of days in a year.  The boolean index indicates whether it is a leap year
or not.


DaySunday  =  7


ISO day number for Sunday


DayThursday  =  4


ISO day number for Thursday


DayTuesday  =  2


ISO day number for Tuesday


DayWednesday  =  3


ISO day number for Wednesday


MonthsPerYear  =  12


Number of months in a year


OneHour  =  1  /  HoursPerDay


One hour as a fraction of a day (suitable for TDateTime)


OneMillisecond  =  1  /  MSecsPerDay


One millisecond as a fraction of a day (suitable for TDateTime)


OneMinute  =  1  /  MinsPerDay


One minute as a fraction of a day (suitable for TDateTime)


OneSecond  =  1  /  SecsPerDay


One second as a fraction of a day (suitable for TDateTime)



                                                                 398

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                RecodeLeaveFieldAsIs  =  High  (  Word  )


                Bitmask deciding what to do with each TDateTime field in recode routines


                WeeksPerFortnight  =  2


                Number of weeks in fortnight


                YearsPerCentury  =  100


                Number of years in a century


                YearsPerDecade  =  10


                Number of years in a decade


                YearsPerMillennium  =  1000


                Number of years in a millenium
                4.4         Procedures  and  functions



                4.4.1        CompareDate

    Synopsis:    Compare 2 dates, disregarding the time of day

Declaration:     function  CompareDate(const  A:  TDateTime;const  B:  TDateTime)
                                                   :  TValueRelationship

    Visibility:   default

Description:     CompareDate compares the date parts of two timestamps A and B and returns the following
                results:


                < 0 if the day part of  A is earlier than the day part of  B.

                0 if  A and B are the on same day (times may differ) .

                > 0  if the day part of  A is later than the day part of  B.


    See also:    CompareTime (401  ),  CompareDateTime (400  ),  SameDate (453  ),  SameTime (455  ),  Same-
                DateTime (454  )


                Listing:  ./datutex/ex99.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e CompareDate          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y' ;


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;
                                                                                 399

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Var
                    Cmp    :   I n t e g e r;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s   ') ;
                    Cmp  :=  CompareDate        (D1  , D2  ) ;
                    I f  Cmp  <0    then
                        w r i t e(' e a r l i e r t h a n  ')
                    e l s e  i f  Cmp  >0   then
                       Write    ( ' l a t e r t h a n  ' )
                    e l s e
                       Write    ( ' e q u a l t o   ') ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(D +1 , D  ) ;
                    T e s t(D -1 , D  ) ;
                    T e s t(D + OneSecond       ,D  ) ;
                    T e s t(D - OneSecond       ,D  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.2        CompareDateTime

    Synopsis:    Compare 2 dates, taking into account the time of day

Declaration:     function  CompareDateTime(const  A:  TDateTime;const  B:  TDateTime)
                                                         :  TValueRelationship

    Visibility:   default

Description:     CompareDateTime compares two timestamps A and B and returns the following results:


                < 0 if  A is earlier in date/time than B.

                0 if  A and B are the same date/time .

                > 0  if  A is later in date/time than B.


    See also:    CompareTime  (401  ),  CompareDate  (399  ),  SameDate  (453  ),  SameTime  (455  ),  SameDate-
                Time (454  )


                Listing:  ./datutex/ex98.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e CompareDateTime             f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;
                                                                                 400

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                Var
                    Cmp    :   I n t e g e r;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s   ') ;
                    Cmp  :=  CompareDateTime           (D1  , D2  ) ;
                    I f  Cmp  <0    then
                        w r i t e(' e a r l i e r t h a n  ')
                    e l s e  i f  Cmp  >0   then
                       Write    ( ' l a t e r t h a n  ' )
                    e l s e
                       Write    ( ' e q u a l t o   ') ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(D +1 , D  ) ;
                    T e s t(D -1 , D  ) ;
                    T e s t(D + OneSecond       ,D  ) ;
                    T e s t(D - OneSecond       ,D  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.3        CompareTime

    Synopsis:    Compares two times of the day, disregarding the date part.

Declaration:     function  CompareTime(const  A:  TDateTime;const  B:  TDateTime)
                                                   :  TValueRelationship

    Visibility:   default

Description:     CompareTime compares the time parts of two timestamps A and B and returns the following
                results:


                < 0 if the time part of  A is earlier than the time part of  B.

                0 if  A and B have the same time part (dates may differ) .

                > 0  if the time part of  A is later than the time part of  B.


    See also:    CompareDateTime  (400  ),  CompareDate  (399  ),  SameDate  (453  ),  SameTime  (455  ),  Same-
                DateTime (454  )


                Listing:  ./datutex/ex100.pp



                                                                                 401

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e CompareTime          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                Var
                    Cmp    :   I n t e g e r;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  h a s  ' ) ;
                    Cmp  :=  CompareDateTime           (D1  , D2  ) ;
                    I f  Cmp  <0    then
                        w r i t e(' e a r l i e r t i m e t h a n  ' )
                    e l s e  i f  Cmp  >0   then
                       Write    ( ' l a t e r t i m e  t h a n  ')
                    e l s e
                       Write    ( ' e q u a l t i m e  w i t h  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.4        DateOf

    Synopsis:    Extract the date part from a DateTime indication.

Declaration:     function  DateOf(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     DateOf extracts the date part from AValue and returns the result.

                Since the TDateTime is actually a double with the date part encoded in the integer part, this
                operation corresponds to a call to Trunc.

    See also:    TimeOf (464  ), YearOf (483  ), MonthOf (443  ), DayOf (404  ), HourOf (419  ), MinuteOf (439  ),
                SecondOf (456  ), MilliSecondOf (434  )


                Listing:  ./datutex/ex1.pp



                                                                                 402

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DateOf       f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(' Date     i s:   ', DateTimeToStr          (DateOf     (Now   ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.5        DateTimeToJulianDate

    Synopsis:    Converts a TDateTime value to a Julian date representation

Declaration:     function  DateTimeToJulianDate(const  AValue:  TDateTime)  :  Double

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    JulianDateToDateTime  (434  ),  TryJulianDateToDateTime  (469  ),  DateTimeToModifiedJu-
                lianDate (403  ), TryModifiedJulianDateToDateTime (469  )
                4.4.6        DateTimeToMac

    Synopsis:    Convert a TDateTime timestamp to a Mac timestamp

Declaration:     function  DateTimeToMac(const  AValue:  TDateTime)  :  Int64

    Visibility:   default

Description:     DateTimeToMac converts the TDateTime value AValue to a valid Mac timestamp indication
                and returns the result.

       Errors:   None.

    See also:    UnixTimeStampToMac (471  ), MacToDateTime (434  ), MacTimeStampToUnix (434  )
                4.4.7        DateTimeToModifiedJulianDate

    Synopsis:    Convert a TDateTime value to a modified Julian date representation

Declaration:     function  DateTimeToModifiedJulianDate(const  AValue:  TDateTime)  :  Double

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (403  ),  JulianDateToDateTime  (434  ),  TryJulianDateToDateTime
                (469  ), TryModifiedJulianDateToDateTime (469  )
                                                                                 403

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.8        DateTimeToUnix

    Synopsis:    Convert a TDateTime value to Unix epoch time

Declaration:     function  DateTimeToUnix(const  AValue:  TDateTime)  :  Int64

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    UnixToDateTime (471  )
                4.4.9        DayOf

    Synopsis:    Extract the day (of month) part from a DateTime value

Declaration:     function  DayOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     DayOf returns the day of the month part of the AValue date/time indication.  It is a number
                between 1 and 31.

                For an example, see YearOf (483  )

    See also:    YearOf  (483  ),  WeekOf  (471  ),  MonthOf  (443  ),  HourOf  (419  ),  MinuteOf  (439  ),  SecondOf
                (456  ), MilliSecondOf (434  )
                4.4.10         DayOfTheMonth

    Synopsis:    Extract the day (of month) part of a DateTime value

Declaration:     function  DayOfTheMonth(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     DayOfTheMonth returns the number of days that have passed since the start of the month
                till the moment indicated by AValue.  This is a one-based number, i.e.  the first day of the
                month will return 1.

                For an example, see the WeekOfTheMonth (471  ) function.

    See also:    DayOfTheYear  (405  ),  WeekOfTheMonth  (471  ),  HourOfTheMonth  (420  ),  MinuteOfThe-
                Month (440  ), SecondOfTheMonth (457  ), MilliSecondOfTheMonth (436  )
                4.4.11         DayOfTheWeek

    Synopsis:    Extracts the day of the week from a DateTime value

Declaration:     function  DayOfTheWeek(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     DayOfTheWeek returns the number of days that have passed since the start of the week till
                the moment indicated by AValue.  This is a one-based number, i.e.  the first day of the week
                will return 1.

    See also:    DayOfTheYear (405  ),  DayOfTheMonth (404  ),  HourOfTheWeek (420  ),  MinuteOfTheWeek
                (440  ), SecondOfTheWeek (457  ), MilliSecondOfTheWeek (436  )



                                                                                 404

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Listing:  ./datutex/ex42.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e WeekOfTheMonth             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n(' Day    o f  t h e  Week                   :  ' ,DayOfTheWeek         ( N ) ) ;
                    W r i t e l n(' Hour     o f  t h e Week                  :  ' ,HourOfTheWeek          (N  ) ) ;
                    W r i t e l n(' M i n u t e o f  t h e  Week              :  ' ,MinuteOfTheWeek            (N ) ) ;
                    W r i t e l n(' S e c o n d o f  t h e  Week              :  ' ,SecondOfTheWeek            (N ) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  Week     :  ' ,
                                  M i l l i S e c o n d O f T h e W e(eNk) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.12         DayOfTheYear

    Synopsis:    Extracts the day of the year from a TDateTime value

Declaration:     function  DayOfTheYear(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     DayOfTheYear returns the number of days that have passed since the start of the year till
                the moment indicated by AValue.  This is a one-based number, i.e.  January 1 will return 1.

                For an example, see the WeekOfTheYear (472  ) function.

    See also:    WeekOfTheYear (472  ), HourOfTheYear (420  ), MinuteOfTheYear (440  ), SecondOfTheYear
                (458  ), MilliSecondOfTheYear (437  )
                4.4.13         DaysBetween

    Synopsis:    Number of whole days between two DateTime values.

Declaration:     function  DaysBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                   :  Integer

    Visibility:   default

Description:     DaysBetween returns the number of whole days between ANow and AThen.  This means the
                fractional part of a day (hours, minutes, etc.)  is dropped.

    See also:    YearsBetween  (484  ),  MonthsBetween  (443  ),  WeeksBetween  (473  ),  HoursBetween  (420  ),
                MinutesBetween (441  ), SecondsBetween (458  ), MilliSecondsBetween (437  )


                Listing:  ./datutex/ex58.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DaysBetween          f u n c t i o n }

                                                                                 405

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  d a y s  b e t w e e n ' ) ;
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  W r i t e l n( '  :   ', DaysBetween        (ANow    ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  Today    -23/24;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -25/24;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -26/24;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    - 5 . 4 ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    - 2 . 5 ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.14         DaysInAMonth

    Synopsis:    Number of days in a month of a certain year.

Declaration:     function  DaysInAMonth(const  AYear:  Word;const  AMonth:  Word)  :  Word

    Visibility:   default

Description:     DaysInYMonth  returns  the  number  of  days  in  the  month  AMonth  in  the  yearAYear.   The
                return value takes leap years into account.

    See also:    WeeksInAYear (474  ),  WeeksInYear (474  ),  DaysInYear (408  ),  DaysInAYear (407  ),  DaysIn-
                Month (407  )


                Listing:  ./datutex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DaysInAMonth           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M   :  Word    ;


                Begin
                    For    Y : = 1 9 9 2 t o  2 0 1 0  do
                       For    M : = 1  t o  1 2  do
                           W r i t e l n(LongMonthNames          [ m ] , '  ' ,Y , '  h a s   ', DaysInAMonth         (Y ,M  ) ,'  *
 * d a y s. ') ;



                                                                                 406

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.15         DaysInAYear

    Synopsis:    Number of days in a particular year.

Declaration:     function  DaysInAYear(const  AYear:  Word)  :  Word

    Visibility:   default

Description:     DaysInAYear returns the number of weeks in the year AYear.  The return value is either 365
                or 366.

    See also:    WeeksInAYear (474  ), WeeksInYear (474  ), DaysInYear (408  ), DaysInMonth (407  ), DaysInA-
                Month (406  )


                Listing:  ./datutex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D a y s I n A Y e a rf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y   :  Word   ;


                Begin
                    For    Y : = 1 9 9 2 t o  2 0 1 0  do
                        W r i t e l n(Y, '  h a s   ', D a y s I n A Y e a(rY ) ,'   d a y s. ') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.16         DaysInMonth

    Synopsis:    Return the number of days in the month in which a date occurs.

Declaration:     function  DaysInMonth(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     DaysInMonth returns the number of days in the month in which AValue falls.  The return
                value takes leap years into account.

    See also:    WeeksInAYear (474  ), WeeksInYear (474  ), DaysInYear (408  ), DaysInAYear (407  ), DaysInA-
                Month (406  )


                Listing:  ./datutex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DaysInMonth          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M   :  Word    ;
                                                                                 407

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Begin
                    For    Y : = 1 9 9 2 t o  2 0 1 0  do
                       For    M : = 1  t o  1 2  do
                           W r i t e l n(LongMonthNames          [ m ] , '  ' ,Y , '  h a s   ', DaysInMonth        (EncodeDate    *
 *    (Y  ,M , 1 ) ) ,'  d a y s. ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.17         DaysInYear

    Synopsis:    Return the number of days in the year in which a date occurs.

Declaration:     function  DaysInYear(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     daysInYear  returns  the  number  of  days  in  the  year  part  of  AValue.  The  return  value  is
                either 365 or 366.

    See also:    WeeksInAYear (474  ), WeeksInYear (474  ), DaysInAYear (407  ), DaysInMonth (407  ), DaysI-
                nAMonth (406  )


                Listing:  ./datutex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D a y s I n Y e a r f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y   :  Word   ;


                Begin
                    For    Y : = 1 9 9 2 t o  2 0 1 0  do
                        W r i t e l n(Y, '  h a s   ', D a y s I n Y e a(rEncodeDate       ( Y , 1 , 1 ) ) ,'  d a y s. ') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.18         DaySpan

    Synopsis:    Calculate the approximate number of days between two DateTime values.

Declaration:     function  DaySpan(const  ANow:  TDateTime;const  AThen:  TDateTime)  :  Double

    Visibility:   default

Description:     DaySpan  returns  the  number  of  Days  between  ANow  and  AThen,  including  any  fractional
                parts of a Day.

    See also:    YearSpan (485  ),  MonthSpan (444  ),  WeekSpan (475  ),  HourSpan (421  ),  MinuteSpan (442  ),
                SecondSpan (459  ), MilliSecondSpan (438  ), DaysBetween (405  )


                Listing:  ./datutex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DaySpan       f u n c t i o n }
                                                                                 408

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  d a y s  b e t w e e n ' ) ;
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  W r i t e l n( '  :   ', DaySpan     (ANow    ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  Today    -23/24;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -25/24;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -26/24;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    - 5 . 4 ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    - 2 . 5 ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.19         DecodeDateDay

    Synopsis:    Decode a DateTime value in year and year of day.

Declaration:     procedure  DecodeDateDay(const  AValue:  TDateTime;var  AYear:  Word;
                                                      var  ADayOfYear:  Word)

    Visibility:   default

Description:     DecodeDateDay decomposes the date indication in AValue and returns the various compo-
                nents in AYear, ADayOfYear.

    See also:    EncodeDateTime  (413  ),  EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay  (412  ),  DecodeDateTime  (410  ),  DecodeDateWeek  (411  ),  DecodeDateMonthWeek
                (410  )


                Listing:  ./datutex/ex83.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDateDay            f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,DoY     :  Word   ;
                    TS   :   TDateTime       ;
                                                                                 409

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Begin
                    DecodeDateDay          (Now   ,Y , DoY  ) ;
                    TS :=  EncodeDateDay          (Y , DoY  ) ;
                    W r i t e l n(' Today     i s   :  ' ,DateToStr       (TS   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.20         DecodeDateMonthWeek

    Synopsis:    Decode a DateTime value in a month, week of month and day of week

Declaration:     procedure  DecodeDateMonthWeek(const  AValue:  TDateTime;var  AYear:  Word;
                                                                var  AMonth:  Word;var  AWeekOfMonth:  Word;
                                                                var  ADayOfWeek:  Word)

    Visibility:   default

Description:     DecodeDateMonthWeek decomposes the date indication in AValue and returns the various
                components in AYear, AMonthAWeekOfMonth and ADayOfWeek.

    See also:    EncodeDateTime  (413  ),  EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay (412  ), DecodeDateTime (410  ), DecodeDateWeek (411  ), DecodeDateDay (409  )


                Listing:  ./datutex/ex85.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDateMonthWeek                f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M ,Wom   , Dow    :  Word    ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateMonthWeek              (Now   ,Y  ,M ,WoM   ,DoW   ) ;
                    TS :=  EncodeDateMonthWeek              (Y  ,M ,WoM   ,Dow   ) ;
                    W r i t e l n(' Today     i s   :  ' ,DateToStr       (TS   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.21         DecodeDateTime

    Synopsis:    Decode a datetime value in a date and time value

Declaration:     procedure  DecodeDateTime(const  AValue:  TDateTime;var  AYear:  Word;
                                                        var  AMonth:  Word;var  ADay:  Word;var  AHour:  Word;
                                                        var  AMinute:  Word;var  ASecond:  Word;
                                                        var  AMilliSecond:  Word)

    Visibility:   default

Description:     DecodeDateTime  decomposes  the  date/time  indication  in  AValue  and  returns  the  various
                components in AYear, AMonth, ADay, AHour, AMinute, ASecond, AMilliSecond


                                                                                 410

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    See also:    EncodeDateTime  (413  ),  EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay  (412  ),  DecodeDateWeek  (411  ),  DecodeDateDay  (409  ),  DecodeDateMonthWeek
                (410  )


                Listing:  ./datutex/ex79.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDateTime             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,Mo  ,D  ,H ,Mi  , S ,MS    :  Word   ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateTime          ( Now   ,Y ,Mo  ,D  ,H , Mi , S ,MS  ) ;
                    TS :=  EncodeDateTime          ( Y ,Mo  ,D  ,H , Mi , S ,MS  ) ;
                    W r i t e l n('Now     i s  :   ', DateTimeToStr          (TS  ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.22         DecodeDateWeek

    Synopsis:    Decode a DateTime value in a week of year and day of week.

Declaration:     procedure  DecodeDateWeek(const  AValue:  TDateTime;var  AYear:  Word;
                                                        var  AWeekOfYear:  Word;var  ADayOfWeek:  Word)

    Visibility:   default

Description:     DecodeDateWeek decomposes the date indication in AValue and returns the various compo-
                nents in AYear, AWeekOfYear, ADayOfWeek.

    See also:    EncodeDateTime  (413  ),  EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay  (412  ),  DecodeDateTime  (410  ),  DecodeDateDay  (409  ),  DecodeDateMonthWeek
                (410  )


                Listing:  ./datutex/ex81.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDateWeek             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,W , Dow    :  Word    ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateWeek          ( Now   ,Y ,W  ,Dow   ) ;
                    TS :=  EncodeDateWeek          ( Y ,W  ,Dow   ) ;
                    W r i t e l n(' Today     i s   :  ' ,DateToStr       (TS   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________


                                                                                 411

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.23         DecodeDayOfWeekInMonth

    Synopsis:    Decode a DateTime value in year, month, day of week parts

Declaration:     procedure  DecodeDayOfWeekInMonth(const  AValue:  TDateTime;
                                                                     var  AYear:  Word;var  AMonth:  Word;
                                                                     var  ANthDayOfWeek:  Word;
                                                                     var  ADayOfWeek:  Word)

    Visibility:   default

Description:     DecodeDayOfWeekInMonth decodes the date AValue in a AYear, AMonth, ADayOfweek and
                ANthDayOfweek.  (This  is  the  N-th  time  that  this  weekday  occurs  in  the  month,  e.g.  the
                third saturday of the month.)

    See also:    NthDayOfWeek (445  ), EncodeDateMonthWeek (413  ), #rtl.sysutils.DayOfWeek (1405   ), En-
                codeDayOfWeekInMonth (414  ), TryEncodeDayOfWeekInMonth (468  )


                Listing:  ./datutex/ex105.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDayOfWeekInMonth                   f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M ,NDoW    ,DoW     :  Word   ;
                    D   :  TDateTime       ;
                Begin
                    DecodeDayOfWeekInMonth                ( Date   ,Y  ,M ,NDoW    ,DoW   ) ;
                    D := EncodeDayOfWeekInMonth                 (Y ,M  ,NDoW   ,DoW   ) ;
                    Write    (DateToStr       (D  ) ,'   i s  t h e  ' ,NDow   , '-  t h  ' ) ;
                    W r i t e l n(formatdateTime          ( ' dddd   ' ,D ) , '  o f  t h e  month    . ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.24         EncodeDateDay

    Synopsis:    Encodes a year and day of year to a DateTime value

Declaration:     function  EncodeDateDay(const  AYear:  Word;const  ADayOfYear:  Word)
                                                      :  TDateTime

    Visibility:   default

Description:     EncodeDateDay encodes the values AYear and ADayOfYear to a date value and returns this
                value.

                For an example, see DecodeDateDay (409  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    EncodeDateMonthWeek  (413  ),  DecodeDateDay  (409  ),  EncodeDateTime  (413  ),  Encode-
                DateWeek (413  ), TryEncodeDateTime (467  ), TryEncodeDateMonthWeek (466  ), TryEncode-
                DateWeek (468  )

                                                                                 412

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.25         EncodeDateMonthWeek

    Synopsis:    Encodes a year, month, week of month and day of week to a DateTime value

Declaration:     function  EncodeDateMonthWeek(const  AYear:  Word;const  AMonth:  Word;
                                                              const  AWeekOfMonth:  Word;
                                                              const  ADayOfWeek:  Word)  :  TDateTime

    Visibility:   default

Description:     EncodeDateTime  encodes  the  values  AYearAMonth,  WeekOfMonth,ADayOfWeek,  to  a  date
                value and returns this value.

                For an example, see DecodeDateMonthWeek (410  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    DecodeDateMonthWeek  (410  ),  EncodeDateTime  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay  (412  ),  TryEncodeDateTime  (467  ),  TryEncodeDateWeek  (468  ),  TryEncodeDate-
                MonthWeek (466  ), TryEncodeDateDay (466  ), NthDayOfWeek (445  )
                4.4.26         EncodeDateTime

    Synopsis:    Encodes a DateTime value from all its parts

Declaration:     function  EncodeDateTime(const  AYear:  Word;const  AMonth:  Word;
                                                      const  ADay:  Word;const  AHour:  Word;
                                                      const  AMinute:  Word;const  ASecond:  Word;
                                                      const  AMilliSecond:  Word)  :  TDateTime

    Visibility:   default

Description:     EncodeDateTime encodes the values AYearAMonth, ADay,AHour, AMinute,ASecond and AMilliSecond
                to a date/time valueand returns this value.

                For an example, see DecodeDateTime (410  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    DecodeDateTime  (410  ),  EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay (412  ), TryEncodeDateTime (467  ), TryEncodeDateWeek (468  ), TryEncodeDateDay
                (466  ), TryEncodeDateMonthWeek (466  )
                4.4.27         EncodeDateWeek

    Synopsis:    Encode a TDateTime value from a year, week and day of week triplet

Declaration:     function  EncodeDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                      const  ADayOfWeek:  Word)  :  TDateTime
                function  EncodeDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word)
                                                        :  TDateTime

    Visibility:   default

Description:     EncodeDateWeek encodes the values AYear, AWeekOfYear and ADayOfWeek to a date value
                and returns this value.

                For an example, see DecodeDateWeek (411  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.



                                                                                 413

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    See also:    EncodeDateMonthWeek  (413  ),  DecodeDateWeek  (411  ),  EncodeDateTime  (413  ),  Encode-
                DateDay  (412  ),  TryEncodeDateTime  (467  ),  TryEncodeDateWeek  (468  ),  TryEncodeDate-
                MonthWeek (466  )
                4.4.28         EncodeDayOfWeekInMonth

    Synopsis:    Encodes a year, month, week, day of week specification to a TDateTime value

Declaration:     function  EncodeDayOfWeekInMonth(const  AYear:  Word;const  AMonth:  Word;
                                                                   const  ANthDayOfWeek:  Word;
                                                                   const  ADayOfWeek:  Word)  :  TDateTime

    Visibility:   default

Description:     EncodeDayOfWeekInMonth  encodes  AYear,  AMonth,  ADayOfweek  and  ANthDayOfweek  to  a
                valid date stamp and returns the result.

                ANthDayOfweekis  the  N-th  time  that  this  weekday  occurs  in  the  month,  e.g.   the  third
                saturday of the month.

                For an example, see DecodeDayOfWeekInMonth (412  ).

       Errors:   If any of the values is not in range, then an EConvertError exception will be raised.

    See also:    NthDayOfWeek (445  ), EncodeDateMonthWeek (413  ), #rtl.sysutils.DayOfWeek (1405   ), De-
                codeDayOfWeekInMonth (412  ), TryEncodeDayOfWeekInMonth (468  )
                4.4.29         EndOfADay

    Synopsis:    Calculates a DateTime value representing the end of a specified day

Declaration:     function  EndOfADay(const  AYear:  Word;const  AMonth:  Word;
                                              const  ADay:  Word)  :  TDateTime;    Overload
                function  EndOfADay(const  AYear:  Word;const  ADayOfYear:  Word)  :  TDateTime
                                              ;    Overload

    Visibility:   default

Description:     EndOfADay  returns  a  TDateTime  value  with  the  date/time  indication  of  the  last  moment
                (23:59:59.999) of the day given by AYear, AMonth, ADay.

                The day may also be indicated with a AYear, ADayOfYear pair.

    See also:    StartOfTheDay  (462  ),  StartOfADay  (460  ),  StartOfTheWeek  (463  ),  StartOfAWeek  (461  ),
                StartOfAMonth (461  ), StartOfTheMonth (463  ), EndOfTheWeek (418  ), EndOfAWeek (415  ),
                EndOfTheYear  (418  ),  EndOfAYear  (416  ),  EndOfTheMonth  (417  ),  EndOfAMonth  (415  ),
                EndOfTheDay (417  )


                Listing:  ./datutex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfADay         f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" End    o f  t h e  day    :  " dd   mmmm     y y y y  hh  :nn  : s s' ;

                                                                                 414

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Var
                    Y ,M , D   :  Word   ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   M  := MonthOf     ( Today    ) ;
                    D := DayOf    ( Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfADay       (Y ,M  ,D ) ) ) ;
                    DecodeDateDay          (Today    , Y ,D ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfADay       (Y , D ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.30         EndOfAMonth

    Synopsis:    Calculate a datetime value representing the last day of the indicated month

Declaration:     function  EndOfAMonth(const  AYear:  Word;const  AMonth:  Word)  :  TDateTime

    Visibility:   default

Description:     EndOfAMonth  e  returns  a  TDateTime  value  with  the  date  of  the  last  day  of  the  month
                indicated by the AYear, AMonth pair.

    See also:    StartOfTheMonth  (463  ),  StartOfAMonth  (461  ),  EndOfTheMonth  (417  ),  EndOfTheYear
                (418  ), EndOfAYear (416  ), StartOfAWeek (461  ), StartOfTheWeek (463  )


                Listing:  ./datutex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfAMonth          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" L a s t  day    o f  t h i s month      :  " dd   mmmm     y y y y ';
                Var
                    Y ,M   :  Word    ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   M  := MonthOf     ( Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfAMonth        ( Y ,M ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.31         EndOfAWeek

    Synopsis:    Return the last moment of day of the week, given a year and a week in the year.

Declaration:     function  EndOfAWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                const  ADayOfWeek:  Word)  :  TDateTime
                function  EndOfAWeek(const  AYear:  Word;const  AWeekOfYear:  Word)
                                                 :  TDateTime

    Visibility:   default
                                                                                 415

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Description:     EndOfAWeek returns a TDateTime value with the date of the last moment (23:59:59:999) on
                the indicated day of the week indicated by the AYear, AWeek, ADayOfWeek values.

                The default value for ADayOfWeek is 7.

    See also:    StartOfTheWeek (463  ), EndOfTheWeek (418  ), EndOfAWeek (415  ), StartOfAMonth (461  ),
                EndOfTheYear (418  ), EndOfAYear (416  ), EndOfTheMonth (417  ), EndOfAMonth (415  )


                Listing:__./datutex/ex35.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 3 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfAWeek          f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" L a s t  day    o f  t h i s  week    :  " dd   mmmm      y y y y hh  :nn  : s s' ;
                    Fmt2    =    '" L a s t-1   day    o f  t h i s  week     :  " dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    Y ,W   :  Word    ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   W  := WeekOf     (Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfAWeek        (Y ,W  ) ) ) ;
                    W r i t e l n(FormatDateTime          ( Fmt2   , EndOfAWeek       ( Y ,W  , 6 ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.32         EndOfAYear

    Synopsis:    Calculate a DateTime value representing the last day of a year

Declaration:     function  EndOfAYear(const  AYear:  Word)  :  TDateTime

    Visibility:   default

Description:     StartOfAYear returns a TDateTime value with the date of the last day of the year AYear
                (December 31).

    See also:    StartOfTheYear (464  ),  EndOfTheYear (418  ),  EndOfAYear (416  ),  EndOfTheMonth (417  ),
                EndOfAMonth (415  ), StartOfAWeek (461  ), StartOfTheWeek (463  )


                Listing:__./datutex/ex27.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfAYear          f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" L a s t  day    o f  t h i s  y e a r :  " dd   mmmm      y y y y';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfAYear        (Y e a r O f(Today    ) ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                 416

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.33         EndOfTheDay

    Synopsis:    Calculate a datetime value that represents the end of a given day.

Declaration:     function  EndOfTheDay(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     EndOfTheDay  extracts  the  date  part  of  AValue  and  returns  a  TDateTime  value  with  the
                date/time indication of the last moment (23:59:59.999) of this day.

    See also:    StartOftheDay  (462  ),  StartOfADay  (460  ),  StartOfTheWeek  (463  ),  StartOfAWeek  (461  ),
                StartOfAMonth (461  ), StartOfTheMonth (463  ), EndOfTheWeek (418  ), EndOfAWeek (415  ),
                EndOfTheYear  (418  ),  EndOfAYear  (416  ),  EndOfTheMonth  (417  ),  EndOfAMonth  (415  ),
                EndOfADay (414  )


                Listing:  ./datutex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfTheDay          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" End    o f  t h e  day    :  " dd   mmmm     y y y y  hh  :nn  : s s' ;



                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfTheDay        ( Today    ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.34         EndOfTheMonth

    Synopsis:    Calculate  a  DateTime  value  representing  the  last  day  of  the  month,  given  a  day  in  that
                month.

Declaration:     function  EndOfTheMonth(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     EndOfTheMonth extracts the year and month parts of AValue and returns a TDateTime value
                with the date of the first day of that year and month as the EndOfAMonth (415  ) function.

    See also:    StartOfAMonth (461  ), StartOfTheMonth (463  ), EndOfAMonth (415  ), EndOfTheYear (418  ),
                EndOfAYear (416  ), StartOfAWeek (461  ), StartOfTheWeek (463  )


                Listing:  ./datutex/ex29.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfTheMonth            f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" l a s t  day    o f  t h i s month      :  " dd   mmmm     y y y y ';

                                                                                 417

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfTheMonth          (Today    ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.35         EndOfTheWeek

    Synopsis:    Calculate a DateTime value which represents the end of a week, given a date in that week.

Declaration:     function  EndOfTheWeek(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     EndOfTheWeek extracts the year and week parts of  AValue and returns a TDateTime value
                with the date of the last day of that week as the EndOfAWeek (415  ) function.

    See also:    StartOfAWeek  (461  ),  StartOfTheWeek  (463  ),  EndOfAWeek  (415  ),  StartOfAMonth  (461  ),
                EndOfTheYear (418  ), EndOfAYear (416  ), EndOfTheMonth (417  ), EndOfAMonth (415  )


                Listing:  ./datutex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfTheWeek           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" l a s t  day    o f  t h i s  week    :  " dd   mmmm      y y y y';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfTheWeek         ( Today    ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.36         EndOfTheYear

    Synopsis:    Calculate a DateTime value representing the last day of a year, given a date in that year.

Declaration:     function  EndOfTheYear(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     EndOfTheYear  extracts  the  year  part  of  AValue  and  returns  a  TDateTime  value  with  the
                date of the last day of that year (December 31), as the EndOfAYear (416  ) function.

    See also:    StartOfAYear (462  ), StartOfTheYear (464  ), EndOfTheMonth (417  ), EndOfAMonth (415  ),
                StartOfAWeek (461  ), StartOfTheWeek (463  ), EndOfAYear (416  )


                Listing:  ./datutex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e EndOfTheYear           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                                                                                 418

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    Fmt   =    '" L a s t  day    o f  t h i s  y e a r :  " dd   mmmm      y y y y';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfTheYear         ( Today    ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.37         HourOf

    Synopsis:    Extract the hour part from a DateTime value.

Declaration:     function  HourOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     HourOf returns the hour of the day part of the AValue date/time indication.  It is a number
                between 0 and 23.

                For an example, see YearOf (483  )

    See also:    YearOf (483  ), WeekOf (471  ), MonthOf (443  ), DayOf (404  ), MinuteOf (439  ), SecondOf (456  ),
                MilliSecondOf (434  )
                4.4.38         HourOfTheDay

    Synopsis:    Calculate the hour of a given DateTime value

Declaration:     function  HourOfTheDay(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     HourOfTheDay returns the number of hours that have passed since the start of the day till
                the moment indicated by AValue.  This is a zero-based number, i.e.  00:59:59 will return 0.

    See also:    HourOfTheYear (420  ), HourOfTheMonth (420  ), HourOfTheWeek (420  ), MinuteOfTheDay
                (439  ), SecondOfTheDay (456  ), MilliSecondOfTheDay (435  )


                Listing:  ./datutex/ex43.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e HourOfTheDay           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n(' Hour     o f  t h e Day                 :   ', HourOfTheDay         (N ) ) ;
                    W r i t e l n(' M i n u t e o f  t h e  Day             :   ', MinuteOfTheDay          (N  ) ) ;
                    W r i t e l n(' S e c o n d o f  t h e  Day             :   ', SecondOfTheDay          (N  ) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  Day    :   ',
                                  M i l l i S e c o n d O f T h e D(aNy) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 419

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.39         HourOfTheMonth

    Synopsis:    Calculate the number of hours passed since the start of the month.

Declaration:     function  HourOfTheMonth(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     HourOfTheMonth returns the number of hours that have passed since the start of the month
                till the moment indicated by AValue.  This is a zero-based number, i.e.  00:59:59 on the first
                day of the month will return 0.

                For an example, see the WeekOfTheMonth (471  ) function.

    See also:    WeekOfTheMonth (471  ), DayOfTheMonth (404  ), MinuteOfTheMonth (440  ), SecondOfThe-
                Month (457  ), MilliSecondOfTheMonth (436  )
                4.4.40         HourOfTheWeek

    Synopsis:    Calculate the number of hours elapsed since the start of the week.

Declaration:     function  HourOfTheWeek(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     HourOfTheWeek returns the number of hours that have passed since the start of the Week
                till the moment indicated by AValue.  This is a zero-based number, i.e.  00:59:59 on the first
                day of the week will return 0.

                For an example, see the DayOfTheWeek (404  ) function.

    See also:    HourOfTheYear (420  ), HourOfTheMonth (420  ), HourOfTheDay (419  ), DayOfTheWeek (404  ),
                MinuteOfTheWeek (440  ), SecondOfTheWeek (457  ), MilliSecondOfTheWeek (436  )
                4.4.41         HourOfTheYear

    Synopsis:    Calculate the number of hours passed since the start of the year.

Declaration:     function  HourOfTheYear(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     HourOfTheYear  returns  the  number  of  hours  that  have  passed  since  the  start  of  the  year
                (January 1, 00:00:00) till the moment indicated by AValue.  This is a zero-based number, i.e.
                January 1 00:59:59 will return 0.

                For an example, see the WeekOfTheYear (472  ) function.

    See also:    WeekOfTheYear  (472  ),  DayOfTheYear  (405  ),  MinuteOfTheYear  (440  ),  SecondOfTheYear
                (458  ), MilliSecondOfTheYear (437  )
                4.4.42         HoursBetween

    Synopsis:    Calculate the number of whole hours between two DateTime values.

Declaration:     function  HoursBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                     :  Int64

    Visibility:   default
                                                                                 420

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Description:     HoursBetween  returns  the  number  of  whole  hours  between  ANow  and  AThen.  This  means
                the fractional part of an hour (minutes,seconds etc.)  is dropped.

    See also:    YearsBetween (484  ), MonthsBetween (443  ), WeeksBetween (473  ), DaysBetween (405  ), Min-
                utesBetween (441  ), SecondsBetween (458  ), MilliSecondsBetween (437  )


                Listing:  ./datutex/ex59.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e H o u r s B e t w e e nf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  h o u r s b e t w e e n  ') ;
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  W r i t e l n( '  :   ', H o u r s B e t w e e(nANow  , AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(61*    OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(122*     OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(306*     OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneHour     ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneHour     ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.43         HourSpan

    Synopsis:    Calculate the approximate number of hours between two DateTime values.

Declaration:     function  HourSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)  :  Double

    Visibility:   default

Description:     HourSpan returns the number of Hours between ANow and AThen, including any fractional
                parts of a Hour.

    See also:    YearSpan  (485  ),  MonthSpan  (444  ),  WeekSpan  (475  ),  DaySpan  (408  ),  MinuteSpan  (442  ),
                SecondSpan (459  ), MilliSecondSpan (438  ), HoursBetween (420  )


                Listing:  ./datutex/ex67.pp

                                                                                 421

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e HourSpan        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  h o u r s b e t w e e n  ') ;
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  W r i t e l n( '  :   ', HourSpan      (ANow    ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(61*    OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(122*     OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(306*     OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneHour     ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneHour     ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.44         IncDay

    Synopsis:    Increase a DateTime value with a number of days.

Declaration:     function  IncDay(const  AValue:  TDateTime;const  ANumberOfDays:  Integer)
                                           :  TDateTime
                function  IncDay(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncDay adds ANumberOfDays days to AValue and returns the resulting date/time.ANumberOfDays
                can be positive or negative.

    See also:    IncYear  (425  ),  #rtl.sysutils.IncMonth  (1450   ),  IncWeek  (425  ),  IncHour  (423  ),  IncMinute
                (424  ), IncSecond (424  ), IncMilliSecond (423  )


                Listing:  ./datutex/ex74.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c D a y  f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;
                                                                                 422

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Begin
                    W r i t e l n('One    Day     f r o m t o d a y  i s  ' ,DateToStr       ( I n c D a y(Today    , 1 ) ) ) ;
                    W r i t e l n('One    Day     ago    f r o m t o d a y  i s  ' ,DateToStr       ( I n c D a y(Today    , - 1 ) *
 *) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.45         IncHour

    Synopsis:    Increase a DateTime value with a number of hours.

Declaration:     function  IncHour(const  AValue:  TDateTime;const  ANumberOfHours:  Int64)
                                            :  TDateTime
                function  IncHour(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncHour adds ANumberOfHours hours to AValue and returns the resulting date/time.ANumberOfHours
                can be positive or negative.

    See also:    IncYear  (425  ),  #rtl.sysutils.IncMonth  (1450   ),  IncWeek  (425  ),  IncDay  (422  ),  IncMinute
                (424  ), IncSecond (424  ), IncMilliSecond (423  )


                Listing:  ./datutex/ex75.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 5
                 ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c H o u r f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n('One     Hour    f r o m  now    i s   ', DateTimeToStr         ( I n c H o u r(Now   , 1 ) ) ) ;
                    W r i t e l n('One     Hour    ago    f r o m  now    i s   ', DateTimeToStr         ( I n c H o u r(Now  , - 1*
 * ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.46         IncMilliSecond

    Synopsis:    Increase a DateTime value with a number of milliseconds.

Declaration:     function  IncMilliSecond(const  AValue:  TDateTime;
                                                      const  ANumberOfMilliSeconds:  Int64)  :  TDateTime
                function  IncMilliSecond(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncMilliSecond  adds  ANumberOfMilliSeconds  milliseconds  to  AValue  and  returns  the
                resulting date/time.ANumberOfMilliSeconds can be positive or negative.

    See also:    IncYear (425  ), #rtl.sysutils.IncMonth (1450   ), IncWeek (425  ), IncDay (422  ), IncHour (423  ),
                IncSecond (424  ), IncMilliSecond (423  )


                Listing:  ./datutex/ex78.pp

                                                                                 423

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c M i l l i S e c o n df u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n('One     M i l l i S e c o n df r o m now     i s  ' ,TimeToStr       ( I n c M i l l i S e c o n*
 *(dNow , 1 ) ) ) ;
                    W r i t e l n('One     M i l l i S e c o n dago    f r o m now     i s  ' ,TimeToStr       ( I n c M i l l i S *
 *e c o n(dNow , - 1 ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.47         IncMinute

    Synopsis:    Increase a DateTime value with a number of minutes.

Declaration:     function  IncMinute(const  AValue:  TDateTime;
                                              const  ANumberOfMinutes:  Int64)  :  TDateTime
                function  IncMinute(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncMinute  adds  ANumberOfMinutes  minutes  to  AValue  and  returns  the  resulting  date/-
                time.ANumberOfMinutes can be positive or negative.

    See also:    IncYear (425  ), #rtl.sysutils.IncMonth (1450   ), IncWeek (425  ), IncDay (422  ), IncHour (423  ),
                IncSecond (424  ), IncMilliSecond (423  )


                Listing:  ./datutex/ex76.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c M i n u t e f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n('One     M i n u t e f r o m now     i s  ' ,TimeToStr       ( I n c M i n u t(eTime   , 1 ) ) ) ;
                    W r i t e l n('One     M i n u t e ago    f r o m now     i s  ' ,TimeToStr       ( I n c M i n u t(eTime   , -*
 * 1 ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.48         IncSecond

    Synopsis:    Increase a DateTime value with a number of seconds.

Declaration:     function  IncSecond(const  AValue:  TDateTime;
                                              const  ANumberOfSeconds:  Int64)  :  TDateTime
                function  IncSecond(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncSecond  adds  ANumberOfSeconds  seconds  to  AValue  and  returns  the  resulting  date/-
                time.ANumberOfSeconds can be positive or negative.

    See also:    IncYear (425  ), #rtl.sysutils.IncMonth (1450   ), IncWeek (425  ), IncDay (422  ), IncHour (423  ),
                IncSecond (424  ), IncMilliSecond (423  )



                                                                                 424

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Listing:  ./datutex/ex77.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c S e c o n d f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n('One     S e c o n d f r o m now     i s  ' ,TimeToStr       ( I n c S e c o n(dTime   , 1 ) ) ) ;
                    W r i t e l n('One     S e c o n d ago    f r o m now     i s  ' ,TimeToStr       ( I n c S e c o n(dTime   , -*
 * 1 ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.49         IncWeek

    Synopsis:    Increase a DateTime value with a number of weeks.

Declaration:     function  IncWeek(const  AValue:  TDateTime;const  ANumberOfWeeks:  Integer)
                                            :  TDateTime
                function  IncWeek(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncWeek adds ANumberOfWeeks weeks to AValue and returns the resulting date/time.ANumberOfWeeks
                can be positive or negative.

    See also:    IncYear  (425  ),  #rtl.sysutils.IncMonth  (1450   ),  IncDay  (422  ),  IncHour  (423  ),  IncMinute
                (424  ), IncSecond (424  ), IncMilliSecond (423  )


                Listing:  ./datutex/ex73.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e IncWeek       f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n('One    Week     f r o m  t o d a y  i s  ' ,DateToStr       ( IncWeek     ( Today    , 1 ) ) ) ;
                    W r i t e l n('One    Week     ago    f r o m  t o d a y  i s  ' ,DateToStr       ( IncWeek     (Today    , - 1*
 * ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.50         IncYear

    Synopsis:    Increase a DateTime value with a number of years.

Declaration:     function  IncYear(const  AValue:  TDateTime;const  ANumberOfYears:  Integer)
                                            :  TDateTime
                function  IncYear(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     IncYear adds ANumberOfYears years to AValue and returns the resulting date/time.  ANumberOfYears
                can be positive or negative.

    See also:    #rtl.sysutils.IncMonth  (1450   ),  IncWeek  (425  ),  IncDay  (422  ),  IncHour  (423  ),  IncMinute
                (424  ), IncSecond (424  ), IncMilliSecond (423  )



                                                                                 425

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Listing:  ./datutex/ex71.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c Y e a r f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n('One     y e a r f r o m  t o d a y  i s  ' ,DateToStr       ( I n c Y e a r(Today    , 1 ) ) ) ;
                    W r i t e l n('One     y e a r ago    f r o m  t o d a y  i s  ' ,DateToStr       ( I n c Y e a r(Today   , - 1*
 * ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.51         InvalidDateDayError

    Synopsis:    Raise an EConvertError exception when a day is not a valid day of a year.

Declaration:     procedure  InvalidDateDayError(const  AYear:  Word;const  ADayOfYear:  Word)

    Visibility:   default

Description:     InvalidDateDayError  raises  an  EConvertError  (1500   )  exception  and  formats  the  error
                message with an appropriate description made up from the parts AYear and ADayOfYear.

                Normally this function should not be needed, the conversion routines call it when they have
                received invalid arguments.

    See also:    InvalidDateWeekError (427  ), InvalidDateTimeError (426  ), InvalidDateMonthWeekError (426  ),
                InvalidDayOfWeekInMonthError (427  )
                4.4.52         InvalidDateMonthWeekError

    Synopsis:    Raise  an  EConvertError  exception  when  a  Year,Month,WeekOfMonth,DayofWeek  is  in-
                valid.

Declaration:     procedure  InvalidDateMonthWeekError(const  AYear:  Word;
                                                                          const  AMonth:  Word;
                                                                          const  AWeekOfMonth:  Word;
                                                                          const  ADayOfWeek:  Word)

    Visibility:   default

Description:     InvalidDateMonthWeekError  raises  an  EConvertError  (1500   )  exception  and  formats  the
                error  message  with  an  appropriate  description  made  up  from  the  parts  AYear,  Amonth,
                AWeekOfMonth and ADayOfWeek.

                Normally this function should not be needed, the conversion routines call it when they have
                received invalid arguments.

    See also:    InvalidDateWeekError (427  ), InvalidDateTimeError (426  ), InvalidDateDayError (426  ), In-
                validDayOfWeekInMonthError (427  )
                4.4.53         InvalidDateTimeError

    Synopsis:    Raise an EConvertError about an invalid date-time specification.


                                                                                 426

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Declaration:     procedure  InvalidDateTimeError(const  AYear:  Word;const  AMonth:  Word;
                                                                 const  ADay:  Word;const  AHour:  Word;
                                                                 const  AMinute:  Word;const  ASecond:  Word;
                                                                 const  AMilliSecond:  Word;
                                                                 const  ABaseDate:  TDateTime)
                procedure  InvalidDateTimeError(const  AYear:  Word;const  AMonth:  Word;
                                                                 const  ADay:  Word;const  AHour:  Word;
                                                                 const  AMinute:  Word;const  ASecond:  Word;
                                                                 const  AMilliSecond:  Word)

    Visibility:  default

Description:     InvalidDateTimeError  raises  an  EConvertError  (1500   )  exception  and  formats  the  error
                message with an appropriate description made up from the parts AYear, AMonth, ADay,AHour,
                AMinute, ASecond and AMilliSecond.

                Normally this function should not be needed, the conversion routines call it when they have
                received invalid arguments.

    See also:    InvalidDateWeekError (427  ), InvalidDateDayError (426  ), InvalidDateMonthWeekError (426  ),
                InvalidDayOfWeekInMonthError (427  )
                4.4.54         InvalidDateWeekError

    Synopsis:    Raise an EConvertError with an invalid Year, WeekOfyear and DayOfWeek specification

Declaration:     procedure  InvalidDateWeekError(const  AYear:  Word;
                                                                  const  AWeekOfYear:  Word;
                                                                  const  ADayOfWeek:  Word)

    Visibility:   default

Description:     InvalidDateWeekError  raises  an  EConvertError  (1500   )  exception  and  formats  the  error
                message with an appropriate description made up from the parts AYear, AWeek, ADayOfWeek

                Normally this function should not be needed, the conversion routines call it when they have
                received invalid arguments.

    See also:    InvalidDateTimeError (426  ), InvalidDateDayError (426  ), InvalidDateMonthWeekError (426  ),
                InvalidDayOfWeekInMonthError (427  )
                4.4.55         InvalidDayOfWeekInMonthError

    Synopsis:    Raise  an  EConvertError  exception  when  a  Year,Month,NthDayofWeek,DayofWeek  is  in-
                valid.

Declaration:     procedure  InvalidDayOfWeekInMonthError(const  AYear:  Word;
                                                                               const  AMonth:  Word;
                                                                               const  ANthDayOfWeek:  Word;
                                                                               const  ADayOfWeek:  Word)

    Visibility:   default

Description:     InvalidDayOfWeekInMonthError  raises  an  EConvertError  (1500   )  exception  and  formats
                the error message with an appropriate description made up from the parts AYear, Amonth,
                ANthDayOfWeek and ADayOfWeek.

                Normally this function should not be needed, the conversion routines call it when they have
                received invalid arguments.



                                                                                 427

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    See also:    InvalidDateWeekError (427  ), InvalidDateTimeError (426  ), InvalidDateDayError (426  ), In-
                validDateMonthWeekError (426  )
                4.4.56         IsInLeapYear

    Synopsis:    Determine whether a date is in a leap year.

Declaration:     function  IsInLeapYear(const  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     IsInLeapYear returns True if the year part of  AValue is leap year, or False if not.

    See also:    YearOf (483  ), IsPM (428  ), IsToday (429  ), IsSameDay (429  )


                Listing:  ./datutex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s I n L e a p Y e a rf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(' C u r r e n t y e a r  i s  l e a p y e a r :  ' ,I s I n L e a p Y e a(rDate   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.57         IsPM

    Synopsis:    Determine whether a time is PM or AM.

Declaration:     function  IsPM(const  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     IsPM returns True if the time part of  AValue is later then 12:00 (PM, or afternoon).

    See also:    YearOf (483  ), IsInLeapYear (428  ), IsToday (429  ), IsSameDay (429  )


                Listing:  ./datutex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e IsPM     f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(' C u r r e n t t i m e  i s PM    :   ', IsPM   (Now   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 428

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.58         IsSameDay

    Synopsis:    Check if two date/time indications are the same day.

Declaration:     function  IsSameDay(const  AValue:  TDateTime;const  ABasis:  TDateTime)
                                                :  Boolean

    Visibility:   default

Description:     IsSameDay checks whether AValue and ABasis have the same date part, and returns True
                if they do, False if not.

    See also:    Today (465  ), Yesterday (486  ), Tomorrow (465  ), IsToday (429  )


                Listing:__./datutex/ex21.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e IsSameDay         f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    I   :  I n t e g e r;
                    D   :  TDateTime       ;


                Begin
                    For    I : = 1  t o  3  do
                        b e g i n
                       D :=  Today   + Random     ( 3 ) - 1 ;
                       Write    ( FormatDateTime          ( ' dd  mmmm      y y y y "  i s  t o d a y :  "  ',D  ) ) ;
                        W r i t e l n(IsSameDay      (D  ,Today    ) ) ;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.59         IsToday

    Synopsis:    Check whether a given date is today.

Declaration:     function  IsToday(const  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     IsToday returns True if  AValue is today's date, and False otherwise.

    See also:    Today (465  ), Yesterday (486  ), Tomorrow (465  ), IsSameDay (429  )


                Listing:__./datutex/ex20.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s T o d a y f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(' Today            :   ' ,I s T o d a y(Today    ) ) ;
                    W r i t e l n(' Tomorrow         :   ' ,I s T o d a y(Tomorrow      ) ) ;
                    W r i t e l n(' Y e s t e r d a y:   ' ,I s T o d a y(Y e s t e r d a y) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________
                                                                                 429

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.60         IsValidDate

    Synopsis:    Check whether a set of values is a valid date indication.

Declaration:     function  IsValidDate(const  AYear:  Word;const  AMonth:  Word;
                                                 const  ADay:  Word)  :  Boolean

    Visibility:   default

Description:     IsValidDate  returns  True  when  the  values  AYear,  AMonth,  ADay  form  a  valid  date  indi-
                cation.  If  one  of  the  values  is  not  valid  (e.g.  the  day  is  invalid  or  does  not  exist  in  that
                particular month), False is returned.

                AYear must be in the range 1..9999 to be valid.

    See also:    IsValidTime (433  ), IsValidDateTime (432  ), IsValidDateDay (430  ), IsValidDateWeek (433  ),
                IsValidDateMonthWeek (431  )


                Listing:  ./datutex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s V a l i d D a t ef u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M , D   :  Word   ;


                Begin
                    For    Y : = 2 0 0 0 t o  2 0 0 4  do
                      For   M : = 1  t o  1 2   do
                         For    D : = 1  t o  3 1  do
                             I f  Not    I s V a l i d D a t(eY ,M ,D  )  then
                                W r i t e l n(D , '  i s  n o t  a   v a l i d day    i n   ' ,Y , '/ ' ,M ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.61         IsValidDateDay

    Synopsis:    Check whether a given year/day of year combination is a valid date.

Declaration:     function  IsValidDateDay(const  AYear:  Word;const  ADayOfYear:  Word)
                                                        :  Boolean

    Visibility:   default

Description:     IsValidDateDay  returns  True  if  AYear  and  ADayOfYear  form  a  valid  date  indication,  or
                False otherwise.

                AYear must be in the range 1..9999 to be valid.

                The ADayOfYear value is checked to see whether it falls within the valid range of dates for
                AYear.

    See also:    IsValidDate (430  ), IsValidTime (433  ), IsValidDateTime (432  ), IsValidDateWeek (433  ), Is-
                ValidDateMonthWeek (431  )


                Listing:  ./datutex/ex9.pp

                                                                                 430

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s V a l i d D a t e D a yf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y   :  Word   ;


                Begin
                    For    Y : = 1 9 9 6 t o  2 0 0 4  do
                        i f    I s V a l i d D a t e D a(yY, 3 6 6 ) then
                           W r i t e l n(Y , '  i s  a   l e a p y e a r ') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.62         IsValidDateMonthWeek

    Synopsis:    Check whether a given year/month/week/day of the week combination is a valid day

Declaration:     function  IsValidDateMonthWeek(const  AYear:  Word;const  AMonth:  Word;
                                                                const  AWeekOfMonth:  Word;
                                                                const  ADayOfWeek:  Word)  :  Boolean

    Visibility:   default

Description:     IsValidDateMonthWeek returns True if AYear, AMonthAWeekOfMonth and ADayOfWeek form
                a valid date indication, or False otherwise.

                AYear must be in the range 1..9999 to be valid.

                The  AWeekOfMonth,ADayOfWeek  values  are  checked  to  see  whether  the  combination  falls
                within the valid range of weeks for the AYear,AMonth combination.

    See also:    IsValidDate  (430  ),  IsValidTime  (433  ),  IsValidDateTime  (432  ),  IsValidDateDay  (430  ),  Is-
                ValidDateWeek (433  )


                Listing:  ./datutex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s V a l i d D a t e M o n t h W e efku n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,W , D   :  Word   ;
                    B   :  B o o l e a n;


                Begin
                    For    Y : = 2 0 0 0 t o  2 0 0 4  do
                        b e g i n
                       B :=  True   ;
                       For    W : = 4  t o  6   do
                           For   D  : = 1  t o  7  do
                               I f B   then
                                  b e g i n
                                  B := I s V a l i d D a t e M o n t h W e(eYk, 1 2 ,W, D ) ;
                                  I f  Not    B   then



                                                                                 431

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                                      i f  (D =1)    then
                                         W r i t e l n(' December        ',Y  , '  h a s  e x a c t l y ' ,W , '  w e e k s. ')
                                      e l s e
                                         W r i t e l n(' December        ',Y  , '  h a s  ' ,W , '  w e e k s  and    ' ,D -1 , '  *
 * d a y s. ') ;
                                  end  ;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.63         IsValidDateTime

    Synopsis:    Check whether a set of values is a valid date and time indication.

Declaration:     function  IsValidDateTime(const  AYear:  Word;const  AMonth:  Word;
                                                        const  ADay:  Word;const  AHour:  Word;
                                                        const  AMinute:  Word;const  ASecond:  Word;
                                                        const  AMilliSecond:  Word)  :  Boolean

    Visibility:   default

Description:     IsValidTime returns True when the values AYear, AMonth, ADay, AHour, AMinute, ASecond
                and AMilliSecond form a valid date and time indication.  If one of the values is not valid
                (e.g.  the seconds are larger than 60), False is returned.

                AYear must be in the range 1..9999 to be valid.

    See also:    IsValidDate  (430  ),  IsValidTime  (433  ),  IsValidDateDay  (430  ),  IsValidDateWeek  (433  ),  Is-
                ValidDateMonthWeek (431  )


                Listing:  ./datutex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s V a l i d D a t e T i m ef u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,Mo  ,D   :  Word    ;
                    H ,M , S ,MS    :  Word   ;
                    I   :  I n t e g e r;


                Begin
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       Y :=2000+     Random     ( 5 ) ;
                       Mo  := Random     ( 1 5 ) ;
                       D := Random     ( 4 0 ) ;
                       H := Random     ( 3 2 ) ;
                       M := Random     ( 9 0 ) ;
                       S := Random     ( 9 0 ) ;
                       MS  := Random     ( 1 5 0 0 ) ;
                        I f  Not    I s V a l i d D a t e T i m(eY,Mo  ,D ,H  ,M , S ,MS  )  then
                           W r i t e l n(Y , '- ' ,Mo  , '- ' ,D  ,'   ' ,H , ': ' ,M , ' : ' ,S , '. ' ,MS  , '  i s  n o t  a   v*
 * a l i d d a t e/ t i m e. ' ) ;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 432

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.64         IsValidDateWeek

    Synopsis:    Check whether a given year/week/day of the week combination is a valid day.

Declaration:     function  IsValidDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                        const  ADayOfWeek:  Word)  :  Boolean

    Visibility:   default

Description:     IsValidDateWeek returns True if  AYear, AWeekOfYear and ADayOfWeek form a valid date
                indication, or False otherwise.

                AYear must be in the range 1..9999 to be valid.

                The ADayOfWeek,ADayOfWeek values are checked to see whether the combination falls within
                the valid range of weeks for AYear.

    See also:    IsValidDate  (430  ),  IsValidTime  (433  ),  IsValidDateTime  (432  ),  IsValidDateDay  (430  ),  Is-
                ValidDateMonthWeek (431  )


                Listing:__./datutex/ex10.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s V a l i d D a t e W e e kf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,W , D   :  Word   ;
                    B   :  B o o l e a n;


                Begin
                    For    Y : = 2 0 0 0 t o  2 0 0 4  do
                        b e g i n
                       B :=  True   ;
                       For    W : = 5 1  t o  5 4  do
                           For   D  : = 1  t o  7  do
                               I f B   then
                                  b e g i n
                                  B := I s V a l i d D a t e W e e(kY,W , D ) ;
                                  I f  Not    B   then
                                      i f  (D =1)    then
                                         W r i t e l n(Y , '  h a s  e x a c t l y ' ,W , '  w e e k s. ')
                                      e l s e
                                         W r i t e l n(Y , '  h a s  ' ,W , '  w e e k s  and    ' ,D -1 ,  '  d a y s. ') ;
                                  end  ;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.65         IsValidTime

    Synopsis:    Check whether a set of values is a valid time indication.

Declaration:     function  IsValidTime(const  AHour:  Word;const  AMinute:  Word;
                                                 const  ASecond:  Word;const  AMilliSecond:  Word)
                                                   :  Boolean

    Visibility:   default

Description:     Check whether a set of values is a valid time indication.



                                                                                 433

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.66         JulianDateToDateTime

    Synopsis:    Convert a Julian date representation to a TDateTime value.

Declaration:     function  JulianDateToDateTime(const  AValue:  Double)  :  TDateTime

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (403  ),  TryJulianDateToDateTime  (469  ),  DateTimeToModifiedJu-
                lianDate (403  ), TryModifiedJulianDateToDateTime (469  )
                4.4.67         MacTimeStampToUnix

    Synopsis:    Convert a Mac timestamp to a Unix timestamp

Declaration:     function  MacTimeStampToUnix(const  AValue:  Int64)  :  Int64

    Visibility:   default

Description:     MacTimeStampToUnix converts the Mac timestamp indication in AValue to a unix timestamp
                indication (epoch time)

       Errors:   None.

    See also:    UnixTimeStampToMac (471  ), DateTimeToMac (403  ), MacToDateTime (434  )
                4.4.68         MacToDateTime

    Synopsis:    Convert a Mac timestamp to a TDateTime timestamp

Declaration:     function  MacToDateTime(const  AValue:  Int64)  :  TDateTime

    Visibility:   default

Description:     MacToDateTime  converts  the  Mac  timestamp  indication  in  AValue  to  a  valid  TDateTime
                indication.

       Errors:   None.

    See also:    UnixTimeStampToMac (471  ), DateTimeToMac (403  ), MacTimeStampToUnix (434  )
                4.4.69         MilliSecondOf

    Synopsis:    Extract the millisecond part from a DateTime value.

Declaration:     function  MilliSecondOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MillisecondOf returns the second of the minute part of the AValue date/time indication.
                It is a number between 0 and 999.

                For an example, see YearOf (483  )

    See also:    YearOf (483  ), WeekOf (471  ), MonthOf (443  ), DayOf (404  ), HourOf (419  ), MinuteOf (439  ),
                MilliSecondOf (434  )



                                                                                 434

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.70         MilliSecondOfTheDay

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the day

Declaration:     function  MilliSecondOfTheDay(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     MilliSecondOfTheDay returns the number of milliseconds that have passed since the start
                of the Day (00:00:00.000) till the moment indicated by AValue.  This is a zero-based number,
                i.e.  00:00:00.000 will return 0.

                For an example, see the HourOfTheDay (419  ) function.

    See also:    MilliSecondOfTheYear (437  ), MilliSecondOfTheMonth (436  ), MilliSecondOfTheWeek (436  ),
                MilliSecondOfTheHour (435  ), MilliSecondOfTheMinute (435  ), MilliSecondOfTheSecond (436  ),
                HourOfTheDay (419  ), MinuteOfTheDay (439  ), SecondOfTheDay (456  )
                4.4.71         MilliSecondOfTheHour

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the hour

Declaration:     function  MilliSecondOfTheHour(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     MilliSecondOfTheHour returns the number of milliseconds that have passed since the start
                of  the  Hour  (HH:00:00.000)  till  the  moment  indicated  by  AValue.   This  is  a  zero-based
                number, i.e.  HH:00:00.000 will return 0.

                For an example, see the MinuteOfTheHour (439  ) function.

    See also:    MilliSecondOfTheYear (437  ), MilliSecondOfTheMonth (436  ), MilliSecondOfTheWeek (436  ),
                MilliSecondOfTheDay (435  ), MilliSecondOfTheMinute (435  ), MilliSecondOfTheSecond (436  ),
                MinuteOfTheHour (439  ), SecondOfTheHour (456  )
                4.4.72         MilliSecondOfTheMinute

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the minute

Declaration:     function  MilliSecondOfTheMinute(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     MilliSecondOfTheMinute  returns  the  number  of  milliseconds  that  have  passed  since  the
                start of the Minute (HH:MM:00.000) till the moment indicated by AValue.  This is a zero-
                based number, i.e.  HH:MM:00.000 will return 0.

                For an example, see the SecondOfTheMinute (457  ) function.

    See also:    MilliSecondOfTheYear (437  ), MilliSecondOfTheMonth (436  ), MilliSecondOfTheWeek (436  ),
                MilliSecondOfTheDay (435  ), MilliSecondOfTheHour (435  ), MilliSecondOfTheMinute (435  ),
                MilliSecondOfTheSecond (436  ), SecondOfTheMinute (457  )


                                                                                 435

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.73         MilliSecondOfTheMonth

    Synopsis:    Calculate number of milliseconds elapsed since the start of the month.

Declaration:     function  MilliSecondOfTheMonth(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     MilliSecondOfTheMonth  returns  the  number  of  milliseconds  that  have  passed  since  the
                start of the month (00:00:00.000) till the moment indicated by AValue.  This is a zero-based
                number, i.e.  00:00:00.000 on the first of the month will return 0.

                For an example, see the WeekOfTheMonth (471  ) function.

    See also:    WeekOfTheMonth (471  ),  DayOfTheMonth (404  ),  HourOfTheMonth (420  ),  MinuteOfThe-
                Month (440  ), SecondOfTheMonth (457  ), MilliSecondOfTheMonth (436  )
                4.4.74         MilliSecondOfTheSecond

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the second

Declaration:     function  MilliSecondOfTheSecond(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MilliSecondOfTheSecond  returns  the  number  of  milliseconds  that  have  passed  since  the
                start of the second (HH:MM:SS.000) till the moment indicated by AValue.  This is a zero-
                based number, i.e.  HH:MM:SS.000 will return 0.

    See also:    MilliSecondOfTheYear (437  ), MilliSecondOfTheMonth (436  ), MilliSecondOfTheWeek (436  ),
                MilliSecondOfTheDay (435  ), MilliSecondOfTheHour (435  ), MilliSecondOfTheMinute (435  ),
                SecondOfTheMinute (457  )


                Listing:  ./datutex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i l l i S e c o n d O f T h e S e c o nfdu n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  S e c o n d :   ' ,
                                  M i l l i S e c o n d O f T h e S e c o(nNd) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.75         MilliSecondOfTheWeek

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the week

Declaration:     function  MilliSecondOfTheWeek(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

                                                                                 436

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Description:     MilliSecondOfTheWeek returns the number of milliseconds that have passed since the start
                of the Week (00:00:00.000) till the moment indicated by AValue.  This is a zero-based number,
                i.e.  00:00:00.000 on the first of the Week will return 0.

                For an example, see the DayOfTheWeek (404  ) function.

    See also:    MilliSecondOfTheYear (437  ), MilliSecondOfTheMonth (436  ), MilliSecondOfTheDay (435  ),
                MilliSecondOfTheHour (435  ), MilliSecondOfTheMinute (435  ), MilliSecondOfTheSecond (436  ),
                DayOfTheWeek (404  ), HourOfTheWeek (420  ), MinuteOfTheWeek (440  ), SecondOfTheWeek
                (457  )
                4.4.76         MilliSecondOfTheYear

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the year.

Declaration:     function  MilliSecondOfTheYear(const  AValue:  TDateTime)  :  Int64

    Visibility:   default

Description:     MilliSecondOfTheYear returns the number of milliseconds that have passed since the start
                of the year (January 1, 00:00:00.000) till the moment indicated by AValue.  This is a zero-
                based number, i.e.  January 1 00:00:00.000 will return 0.

                For an example, see the WeekOfTheYear (472  ) function.

    See also:    WeekOfTheYear  (472  ),  DayOfTheYear  (405  ),  HourOfTheYear  (420  ),  MinuteOfTheYear
                (440  ), SecondOfTheYear (458  ), MilliSecondOfTheYear (437  )
                4.4.77         MilliSecondsBetween

    Synopsis:    Calculate the number of whole milliseconds between two DateTime values.

Declaration:     function  MilliSecondsBetween(const  ANow:  TDateTime;
                                                              const  AThen:  TDateTime)  :  Int64

    Visibility:   default

Description:     MillisSecondsBetween returns the number of whole milliseconds between ANow and AThen.
                This means a fractional part of a millisecond is dropped.

    See also:    YearsBetween (484  ), MonthsBetween (443  ), WeeksBetween (473  ), DaysBetween (405  ), Hours-
                Between (420  ), MinutesBetween (441  ), SecondsBetween (458  )


                Listing:  ./datutex/ex62.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i l l i S e c o n d s B e t w e efnu n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i l l i s e c o n d sb e t w e e n ') ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i l l i S e c o n d s B e t w e(eAnNow  ,AThen    ) ) ;
                end   ;
                                                                                 437

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 - ( 0 . 9 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 0 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 1 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.78         MilliSecondSpan

    Synopsis:    Calculate the approximate number of milliseconds between two DateTime values.

Declaration:     function  MilliSecondSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                         :  Double

    Visibility:   default

Description:     MilliSecondSpan returns the number of milliseconds between ANow and AThen.  Since mil-
                lisecond is the smallest fraction of a TDateTime indication, the returned number will always
                be an integer value.

    See also:    YearSpan (485  ), MonthSpan (444  ), WeekSpan (475  ), DaySpan (408  ), HourSpan (421  ), Min-
                uteSpan (442  ), SecondSpan (459  ), MilliSecondsBetween (437  )


                Listing:  ./datutex/ex70.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i l l i S e c o n d S p a nf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i l l i s e c o n d sb e t w e e n ') ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i l l i S e c o n d S p a(nANow  ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 - ( 0 . 9 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 0 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 1 *O n e M i l l i S e c o n)d;
                                                                                 438

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.79         MinuteOf

    Synopsis:    Extract the minute part from a DateTime value.

Declaration:     function  MinuteOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MinuteOf returns the minute of the hour part of the AValue date/time indication.  It is a
                number between 0 and 59.

                For an example, see YearOf (483  )

    See also:    YearOf (483  ), WeekOf (471  ), MonthOf (443  ), DayOf (404  ), HourOf (419  ), SecondOf (456  ),
                MilliSecondOf (434  )
                4.4.80         MinuteOfTheDay

    Synopsis:    Calculate the number of minutes elapsed since the start of the day

Declaration:     function  MinuteOfTheDay(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MinuteOfTheDay returns the number of minutes that have passed since the start of the Day
                (00:00:00) till the moment indicated by AValue.  This is a zero-based number, i.e.  00:00:59
                will return 0.

                For an example, see the HourOfTheDay (419  ) function.

    See also:    MinuteOfTheYear (440  ), MinuteOfTheMonth (440  ), MinuteOfTheWeek (440  ), MinuteOfThe-
                Hour (439  ), HourOfTheDay (419  ), SecondOfTheDay (456  ), MilliSecondOfTheDay (435  )
                4.4.81         MinuteOfTheHour

    Synopsis:    Calculate the number of minutes elapsed since the start of the hour

Declaration:     function  MinuteOfTheHour(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MinuteOfTheHour  returns  the  number  of  minutes  that  have  passed  since  the  start  of  the
                Hour  (HH:00:00)  till  the  moment  indicated  by  AValue.  This  is  a  zero-based  number,  i.e.
                HH:00:59 will return 0.

    See also:    MinuteOfTheYear (440  ), MinuteOfTheMonth (440  ), MinuteOfTheWeek (440  ), MinuteOfThe-
                Day (439  ), SecondOfTheHour (456  ), MilliSecondOfTheHour (435  )


                Listing:  ./datutex/ex44.pp
                                                                                 439

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e MinuteOfTheHour             f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n(' M i n u t e o f  t h e  Hour              :  ' ,MinuteOfTheHour            (N ) ) ;
                    W r i t e l n(' S e c o n d o f  t h e  Hour              :  ' ,SecondOfTheHour            (N ) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  Hour     :  ' ,
                                  M i l l i S e c o n d O f T h e H o(uNr) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.82         MinuteOfTheMonth

    Synopsis:    Calculate number of minutes elapsed since the start of the month.

Declaration:     function  MinuteOfTheMonth(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MinuteOfTheMonth returns the number of minutes that have passed since the start of the
                Month  (00:00:00)  till  the  moment  indicated  by  AValue.  This  is  a  zero-based  number,  i.e.
                00:00:59 on the first day of the month will return 0.

                For an example, see the WeekOfTheMonth (471  ) function.

    See also:    WeekOfTheMonth (471  ),  DayOfTheMonth (404  ),  HourOfTheMonth (420  ),  MinuteOfThe-
                Month (440  ), SecondOfTheMonth (457  ), MilliSecondOfTheMonth (436  )
                4.4.83         MinuteOfTheWeek

    Synopsis:    Calculate the number of minutes elapsed since the start of the week

Declaration:     function  MinuteOfTheWeek(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MinuteOfTheWeek  returns  the  number  of  minutes  that  have  passed  since  the  start  of  the
                week  (00:00:00)  till  the  moment  indicated  by  AValue.   This  is  a  zero-based  number,  i.e.
                00:00:59 on the first day of the week will return 0.

                For an example, see the DayOfTheWeek (404  ) function.

    See also:    MinuteOfTheYear (440  ), MinuteOfTheMonth (440  ), MinuteOfTheDay (439  ), MinuteOfThe-
                Hour  (439  ),  DayOfTheWeek  (404  ),  HourOfTheWeek  (420  ),  SecondOfTheWeek  (457  ),  Mil-
                liSecondOfTheWeek (436  )
                4.4.84         MinuteOfTheYear

    Synopsis:    Calculate the number of minutes elapsed since the start of the year

Declaration:     function  MinuteOfTheYear(const  AValue:  TDateTime)  :  LongWord



                                                                                 440

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    Visibility:  default

Description:     MinuteOfTheYear returns the number of minutes that have passed since the start of the year
                (January 1, 00:00:00) till the moment indicated by AValue.  This is a zero-based number, i.e.
                January 1 00:00:59 will return 0.

                For an example, see the WeekOfTheYear (472  ) function.

    See also:    WeekOfTheYear  (472  ),  DayOfTheYear  (405  ),  HourOfTheYear  (420  ),  MinuteOfTheYear
                (440  ), SecondOfTheYear (458  ), MilliSecondOfTheYear (437  )
                4.4.85         MinutesBetween

    Synopsis:    Calculate the number of whole minutes between two DateTime values.

Declaration:     function  MinutesBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                        :  Int64

    Visibility:   default

Description:     MinutesBetween returns the number of whole minutes between ANow and AThen.  This means
                the fractional part of a minute (seconds, milliseconds etc.)  is dropped.

    See also:    YearsBetween (484  ), MonthsBetween (443  ), WeeksBetween (473  ), DaysBetween (405  ), Hours-
                Between (420  ), SecondsBetween (458  ), MilliSecondsBetween (437  )


                Listing:__./datutex/ex60.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 6 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i n u t e s B e t w e e nf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i n u t e s b e t w e e n ' ) ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i n u t e s B e t w e e(nANow  ,AThen     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(61*    OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(122*     OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(306*     OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 441

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.86         MinuteSpan

    Synopsis:    Calculate the approximate number of minutes between two DateTime values.

Declaration:     function  MinuteSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                 :  Double

    Visibility:   default

Description:     MinuteSpan returns the number of minutes between ANow and AThen,  including any frac-
                tional parts of a minute.

    See also:    YearSpan (485  ), MonthSpan (444  ), WeekSpan (475  ), DaySpan (408  ), HourSpan (421  ), Sec-
                ondSpan (459  ), MilliSecondSpan (438  ), MinutesBetween (441  )


                Listing:  ./datutex/ex68.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i n u t e S p a n f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i n u t e s b e t w e e n ' ) ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i n u t e S p a(nANow   ,AThen     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(61*    OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(122*     OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(306*     OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.87         ModifiedJulianDateToDateTime

    Synopsis:    Convert a modified Julian date representation to a TDateTime value.

Declaration:     function  ModifiedJulianDateToDateTime(const  AValue:  Double)  :  TDateTime

    Visibility:   default

Description:     Not yet implemented.



                                                                                 442

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (403  ),  JulianDateToDateTime  (434  ),  TryJulianDateToDateTime
                (469  ), DateTimeToModifiedJulianDate (403  ), TryModifiedJulianDateToDateTime (469  )
                4.4.88         MonthOf

    Synopsis:    Extract the month from a given date.

Declaration:     function  MonthOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MonthOf returns the month part of the AValue date/time indication.  It is a number between
                1 and 12.

                For an example, see YearOf (483  )

    See also:    YearOf (483  ), DayOf (404  ), WeekOf (471  ), HourOf (419  ), MinuteOf (439  ), SecondOf (456  ),
                MilliSecondOf (434  )
                4.4.89         MonthOfTheYear

    Synopsis:    Extract the month of a DateTime indication.

Declaration:     function  MonthOfTheYear(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MonthOfTheYear extracts the month part of Avalue and returns it.  It is an alias for MonthOf
                (443  ),  and  is  provided  for  completeness  only,  corresponding  to  the  other  PartOfTheYear
                functions.

                For an example, see the WeekOfTheYear (472  ) function.

    See also:    MonthOf (443  ), WeekOfTheYear (472  ), DayOfTheYear (405  ), HourOfTheYear (420  ), Min-
                uteOfTheYear (440  ), SecondOfTheYear (458  ), MilliSecondOfTheYear (437  )
                4.4.90         MonthsBetween

    Synopsis:    Calculate the number of whole months between two DateTime values

Declaration:     function  MonthsBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                      :  Integer

    Visibility:   default

Description:     MonthsBetween returns the number of whole months between ANow and AThen.  This number
                is an approximation, based on an average number of days of 30.4375 per month (average over
                4 years).  This means the fractional part of a month is dropped.

    See also:    YearsBetween (484  ), WeeksBetween (473  ), DaysBetween (405  ), HoursBetween (420  ), Min-
                utesBetween (441  ), SecondsBetween (458  ), MilliSecondsBetween (437  )


                Listing:  ./datutex/ex56.pp
                                                                                 443

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e MonthsBetween            f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  months      b e t w e e n ' ) ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', MonthsBetween         ( ANow   , AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.91         MonthSpan

    Synopsis:    Calculate the approximate number of months between two DateTime values.

Declaration:     function  MonthSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                :  Double

    Visibility:   default

Description:     MonthSpan returns the number of month between ANow and AThen, including any fractional
                parts of a month.  This number is an approximation, based on an average number of days of
                30.4375 per month (average over 4 years).

    See also:    YearSpan  (485  ),  WeekSpan  (475  ),  DaySpan  (408  ),  HourSpan  (421  ),  MinuteSpan  (442  ),
                SecondSpan (459  ), MilliSecondSpan (438  ), MonthsBetween (443  )


                Listing:  ./datutex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e MonthSpan         f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;
                                                                                 444

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  months      b e t w e e n ' ) ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', MonthSpan      ( ANow   , AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.92         NthDayOfWeek

    Synopsis:    Calculate which occurrence of weekday in the month a given day represents

Declaration:     function  NthDayOfWeek(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     NthDayOfWeek returns the occurence of the weekday of  AValue in the month.  This is the
                N-th time that this weekday occurs in the month (e.g.  the third saturday of the month).

    See also:    EncodeDateMonthWeek (413  ), #rtl.sysutils.DayOfWeek (1405   ), DecodeDayOfWeekInMonth
                (412  ), EncodeDayOfWeekInMonth (414  ), TryEncodeDayOfWeekInMonth (468  )


                Listing:  ./datutex/ex104.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e NthDayOfWeek           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    Write    ( 'Today      i s  t h e  ' ,NthDayOfWeek         ( Today    ) , '- t h  ' ) ;
                    W r i t e l n(formatdateTime          ( ' dddd   ' ,Today    ) , '  o f  t h e  month    . ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________


                                                                                 445

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.93         PreviousDayOfWeek

    Synopsis:    Given a day of the week, return the previous day of the week.

Declaration:     function  PreviousDayOfWeek(DayOfWeek:  Word)  :  Word

    Visibility:   default

Description:     PreviousDayOfWeek  returns  the  previous  day  of  the  week.  If  the  current  day  is  the  first
                day of the week (1) then the last day will be returned (7).

 Remark:         Note that the days of the week are in ISO notation, i.e.  1-based.

    See also:    Yesterday (486  )


                Listing:  ./datutex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e P r e v i o u s D a y O f W e e kf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    D   :  Word   ;


                Begin
                    For    D : = 1  t o  7  do
                        W r i t e l n('P r e v i o u s day    o f  ' ,D , '   i s  :   ', P r e v i o u s D a y O f W e(eDk) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.94         RecodeDate

    Synopsis:    Replace date part of a TDateTime value with another date.

Declaration:     function  RecodeDate(const  AValue:  TDateTime;const  AYear:  Word;
                                                const  AMonth:  Word;const  ADay:  Word)  :  TDateTime

    Visibility:   default

Description:     RecodeDate replaces the date part of the timestamp AValue with the date specified in AYear,
                AMonth, ADay.  All other parts (the time part) of the date/time stamp are left untouched.

       Errors:   If one of the AYear, AMonth, ADay values is not within a valid range then an EConvertError
                exception is raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute
                (450  ), RecodeSecond (451  ), RecodeDate (446  ), RecodeTime (452  ), RecodeDateTime (447  )


                Listing:  ./datutex/ex94.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e D a t e f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';



                                                                                 446

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e D a t e(Now  , 2 0 0 1 , 1 , 1 ) ) ;
                    W r i t e l n(' T h i s moment       on   t h e  f i r s t o f   t h e  m i l l e n i u m:   ', S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.95         RecodeDateTime

    Synopsis:    Replace selected parts of a TDateTime value with other values

Declaration:     function  RecodeDateTime(const  AValue:  TDateTime;const  AYear:  Word;
                                                      const  AMonth:  Word;const  ADay:  Word;
                                                      const  AHour:  Word;const  AMinute:  Word;
                                                      const  ASecond:  Word;const  AMilliSecond:  Word)
                                                        :  TDateTime

    Visibility:   default

Description:     RecodeDateTime replaces selected parts of the timestamp AValue with the date/time values
                specified in AYear,  AMonth,  ADay,  AHour,  AMinute,  ASecond and AMilliSecond.  If any of
                these  values  equals  the  pre-defined  constant  RecodeLeaveFieldAsIs  (399  ),  then  the  corre-
                sponding part of the date/time stamp is left untouched.

       Errors:   If  one  of  the  values  AYear,  AMonth,  ADay,  AHour,  AMinute,  ASecondAMilliSecond  is  not
                within a valid range (RecodeLeaveFieldAsIs excepted) then an EConvertError exception
                is raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute
                (450  ), RecodeSecond (451  ), RecodeMilliSecond (449  ), RecodeDate (446  ), RecodeTime (452  ),
                TryRecodeDateTime (470  )


                Listing:  ./datutex/ex96.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeDateTime             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;
                    D   :  TDateTime         ;


                Begin
                    D := Now   ;
                    D := RecodeDateTime           (D , 2 0 0 0 , 2 ,R e c o d e L e a v e F i e l d A s,I0s, 0 , 0 , 0 ) ;
                    S := FormatDateTime           (Fmt   ,D ) ;
                    W r i t e l n(' T h i s moment       i n  f e b r u a r i2 0 0 0  :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________


                                                                                 447

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.96         RecodeDay

    Synopsis:    Replace day part of a TDateTime value with another day.

Declaration:     function  RecodeDay(const  AValue:  TDateTime;const  ADay:  Word)  :  TDateTime

    Visibility:   default

Description:     RecodeDay replaces the Day part of the timestamp AValue with ADay.  All other parts of
                the date/time stamp are left untouched.

       Errors:   If the ADay value is not within a valid range (1..12) then an EConvertError exception is
                raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeHour (448  ), RecodeMinute (450  ), RecodeSec-
                ond  (451  ),  RecodeMilliSecond  (449  ),  RecodeDate  (446  ),  RecodeTime  (452  ),  RecodeDate-
                Time (447  )


                Listing:  ./datutex/ex89.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeDay         f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,RecodeDay       (Now   , 1 ) ) ;
                    W r i t e l n(' T h i s moment       on   t h e  f i r s t o f   t h e month      :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.97         RecodeHour

    Synopsis:    Replace hours part of a TDateTime value with another hour.

Declaration:     function  RecodeHour(const  AValue:  TDateTime;const  AHour:  Word)
                                                 :  TDateTime

    Visibility:   default

Description:     RecodeHour replaces the Hour part of the timestamp AValue with AHour.  All other parts
                of the date/time stamp are left untouched.

       Errors:   If the AHour value is not within a valid range (0..23) then an EConvertError exception is
                raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeMinute (450  ), RecodeSec-
                ond  (451  ),  RecodeMilliSecond  (449  ),  RecodeDate  (446  ),  RecodeTime  (452  ),  RecodeDate-
                Time (447  )


                Listing:  ./datutex/ex90.pp

                                                                                 448

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeHour          f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,RecodeHour        (Now   , 0 ) ) ;
                    W r i t e l n(' Today    ,  i n  t h e  f i r s t  h o u r :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.98         RecodeMilliSecond

    Synopsis:    Replace milliseconds part of a TDateTime value with another millisecond.

Declaration:     function  RecodeMilliSecond(const  AValue:  TDateTime;
                                                           const  AMilliSecond:  Word)  :  TDateTime

    Visibility:   default

Description:     RecodeMilliSecond replaces the millisecond part of the timestamp AValue with AMilliSecond.
                All other parts of the date/time stamp are left untouched.

       Errors:   If  the  AMilliSecond  value  is  not  within  a  valid  range  (0..999)  then  an  EConvertError
                exception is raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute
                (450  ), RecodeSecond (451  ), RecodeDate (446  ), RecodeTime (452  ), RecodeDateTime (447  )


                Listing:  ./datutex/ex93.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e M i l l i S e c o n df u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e M i l l i S e c o n(dNow , 0 ) ) ;
                    W r i t e l n(' T h i s moment     ,   m i l l i s e c o n d ss t r i p p e d:   ',S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                 449

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.99         RecodeMinute

    Synopsis:    Replace minutse part of a TDateTime value with another minute.

Declaration:     function  RecodeMinute(const  AValue:  TDateTime;const  AMinute:  Word)
                                                     :  TDateTime

    Visibility:   default

Description:     RecodeMinute replaces the Minute part of the timestamp AValue with AMinute.  All other
                parts of the date/time stamp are left untouched.

       Errors:   If the AMinute value is not within a valid range (0..59) then an EConvertError exception
                is raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeSec-
                ond  (451  ),  RecodeMilliSecond  (449  ),  RecodeDate  (446  ),  RecodeTime  (452  ),  RecodeDate-
                Time (447  )


                Listing:  ./datutex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e M i n u t ef u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e M i n u t(eNow   , 0 ) ) ;
                    W r i t e l n(' T h i s moment       i n  t h e  f i r s t m i n u t e  o f  t h e  h o u r:  ' ,S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.100          RecodeMonth

    Synopsis:    Replace month part of a TDateTime value with another month.

Declaration:     function  RecodeMonth(const  AValue:  TDateTime;const  AMonth:  Word)
                                                   :  TDateTime

    Visibility:   default

Description:     RecodeMonth  replaces  the  Month  part  of  the  timestamp  AValue  with  AMonth.   All  other
                parts of the date/time stamp are left untouched.

       Errors:   If the AMonth value is not within a valid range (1..12) then an EConvertError exception is
                raised.

    See also:    RecodeYear (452  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute (450  ), RecodeSec-
                ond  (451  ),  RecodeMilliSecond  (449  ),  RecodeDate  (446  ),  RecodeTime  (452  ),  RecodeDate-
                Time (447  )


                Listing:  ./datutex/ex88.pp



                                                                                 450

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeMonth          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,RecodeMonth         (Now   , 5 ) ) ;
                    W r i t e l n(' T h i s moment       i n  May    :   ', S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.101          RecodeSecond

    Synopsis:    Replace seconds part of a TDateTime value with another second.

Declaration:     function  RecodeSecond(const  AValue:  TDateTime;const  ASecond:  Word)
                                                     :  TDateTime

    Visibility:   default

Description:     RecodeSecond replaces the Second part of the timestamp AValue with ASecond.  All other
                parts of the date/time stamp are left untouched.

       Errors:   If the ASecond value is not within a valid range (0..59) then an EConvertError exception
                is raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute
                (450  ),  RecodeMilliSecond  (449  ),  RecodeDate  (446  ),  RecodeTime  (452  ),  RecodeDateTime
                (447  )


                Listing:  ./datutex/ex92.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e S e c o n df u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e S e c o n(dNow   , 0 ) ) ;
                    W r i t e l n(' T h i s moment     ,  s e c o n d s s t r i p p e d :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 451

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.102          RecodeTime

    Synopsis:    Replace time part of a TDateTime value with another time.

Declaration:     function  RecodeTime(const  AValue:  TDateTime;const  AHour:  Word;
                                                const  AMinute:  Word;const  ASecond:  Word;
                                                const  AMilliSecond:  Word)  :  TDateTime

    Visibility:   default

Description:     RecodeTime replaces the time part of the timestamp AValue with the date specified in AHour,
                AMinute, ASecond and AMilliSecond.  All other parts (the date part) of the date/time stamp
                are left untouched.

       Errors:   If one of the values AHour, AMinute, ASecondAMilliSecond is not within a valid range then
                an EConvertError exception is raised.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute
                (450  ), RecodeSecond (451  ), RecodeMilliSecond (449  ), RecodeDate (446  ), RecodeDateTime
                (447  )


                Listing:  ./datutex/ex95.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeTime          f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,RecodeTime        (Now   , 8 , 0 , 0 , 0 ) ) ;
                    W r i t e l n(' Today    ,  8  AM    :  ' ,S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.103          RecodeYear

    Synopsis:    Replace year part of a TDateTime value with another year.

Declaration:     function  RecodeYear(const  AValue:  TDateTime;const  AYear:  Word)
                                                 :  TDateTime

    Visibility:   default

Description:     RecodeYear replaces the year part of the timestamp AValue with AYear.  All other parts of
                the date/time stamp are left untouched.

       Errors:   If the AYear value is not within a valid range (1..9999) then an EConvertError exception
                is raised.

    See also:    RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute (450  ), RecodeSec-
                ond  (451  ),  RecodeMilliSecond  (449  ),  RecodeDate  (446  ),  RecodeTime  (452  ),  RecodeDate-
                Time (447  )



                                                                                 452

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Listing:  ./datutex/ex87.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e Y e a r f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e Y e a r(Now  , 1 9 9 9 ) ) ;
                    W r i t e l n(' T h i s moment       i n  1 9 9 9  :  ' ,S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.104          SameDate

    Synopsis:    Check whether two TDateTime values have the same date part.

Declaration:     function  SameDate(const  A:  TDateTime;const  B:  TDateTime)  :  Boolean

    Visibility:   default

Description:     SameDate compares the date parts of two timestamps A and B and returns True if they are
                equal, False if they are not.

                The function simply checks whether CompareDate (399  ) returns zero.

    See also:    CompareDateTime (400  ), CompareDate (399  ), CompareTime (401  ), SameDateTime (454  ),
                SameTime (455  )


                Listing:  ./datutex/ex102.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e SameDate        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s  t h e  same     d a t e  a s  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ,'   :  ' ,SameDate      ( D1  ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                                                                                 453

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.105          SameDateTime

    Synopsis:    Check whether two TDateTime values have the same date and time parts.

Declaration:     function  SameDateTime(const  A:  TDateTime;const  B:  TDateTime)  :  Boolean

    Visibility:   default

Description:     SameDateTime compares the date/time parts of two timestamps A and B and returns True
                if they are equal, False if they are not.

                The function simply checks whether CompareDateTime (400  ) returns zero.

    See also:    CompareDateTime (400  ), CompareDate (399  ), CompareTime (401  ), SameDate (453  ), Same-
                Time (455  )


                Listing:  ./datutex/ex101.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e SameDateTime           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s  t h e  same     d a t e t i m e a s  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ,'   :  ' ,SameDateTime         ( D1  ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________


                                                                                 454

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.106          SameTime

    Synopsis:    Check whether two TDateTime values have the same time part.

Declaration:     function  SameTime(const  A:  TDateTime;const  B:  TDateTime)  :  Boolean

    Visibility:   default

Description:     SameTime compares the time parts of two timestamps A and B and returns True if they are
                equal, False if they are not.

                The function simply checks whether CompareTime (401  ) returns zero.

    See also:    CompareDateTime (400  ), CompareDate (399  ), CompareTime (401  ), SameDateTime (454  ),
                SameDate (453  )


                Listing:  ./datutex/ex103.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e SameTime        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s  t h e  same     t i m e  a s  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ,'   :  ' ,SameTime      ( D1  ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.107          ScanDateTime

    Synopsis:    Scans a string for a DateTime pattern and returns the date/time

Declaration:     function  ScanDateTime(const  Pattern:  String;const  s:  String;
                                                   const  fmt:  TFormatSettings;startpos:  Integer)
                                                     :  tdatetime;    Overload
                function  ScanDateTime(const  Pattern:  String;const  s:  String;
                                                   startpos:  Integer)  :  tdatetime;    Overload

    Visibility:   default



                                                                                 455

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Description:     ScanDateTime scans string S for the date/time pattern Pattern, starting at position StartPos
                (default 1).  Optionally, the format settings fmt can be specified.

                In effect, this function does the opposite of what FormatDateTime (1441   ) does.  The Pattern
                variable must contain a valid date/time pattern:  note that not all possible formatdatetime
                patterns can be recognized, e.g., hn cannot be detected properly.

       Errors:   In case of an error, a EConvertError (397  ) exception is raised.

    See also:    FormatDateTime (397  )
                4.4.108          SecondOf

    Synopsis:    Extract the second part from a DateTime value.

Declaration:     function  SecondOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     SecondOf returns the second of the minute part of the AValue date/time indication.  It is a
                number between 0 and 59.

                For an example, see YearOf (483  )

    See also:    YearOf (483  ), WeekOf (471  ), MonthOf (443  ), DayOf (404  ), HourOf (419  ), MinuteOf (439  ),
                MilliSecondOf (434  )
                4.4.109          SecondOfTheDay

    Synopsis:    Calculate the number of seconds elapsed since the start of the day

Declaration:     function  SecondOfTheDay(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     SecondOfTheDay  returns  the  number  of  seconds  that  have  passed  since  the  start  of  the
                Day  (00:00:00)  till  the  moment  indicated  by  AValue.   This  is  a  zero-based  number,  i.e.
                00:00:00.999 return 0.

                For an example, see the HourOfTheDay (419  ) function.

    See also:    SecondOfTheYear (458  ), SecondOfTheMonth (457  ), SecondOfTheWeek (457  ), SecondOfThe-
                Hour (456  ), SecondOfTheMinute (457  ), HourOfTheDay (419  ), MinuteOfTheDay (439  ), Mil-
                liSecondOfTheDay (435  )
                4.4.110          SecondOfTheHour

    Synopsis:    Calculate the number of seconds elapsed since the start of the hour

Declaration:     function  SecondOfTheHour(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     SecondOfTheHour  returns  the  number  of  seconds  that  have  passed  since  the  start  of  the
                Hour  (HH:00:00)  till  the  moment  indicated  by  AValue.  This  is  a  zero-based  number,  i.e.
                HH:00:00.999 return 0.

                For an example, see the MinuteOfTheHour (439  ) function.

    See also:    SecondOfTheYear (458  ), SecondOfTheMonth (457  ), SecondOfTheWeek (457  ), SecondOfThe-
                Day (456  ), SecondOfTheMinute (457  ), MinuteOfTheHour (439  ), MilliSecondOfTheHour (435  )



                                                                                 456

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.111          SecondOfTheMinute

    Synopsis:    Calculate the number of seconds elapsed since the start of the minute

Declaration:     function  SecondOfTheMinute(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     SecondOfTheMinute returns the number of seconds that have passed since the start of the
                minute (HH:MM:00) till the moment indicated by AValue.  This is a zero-based number, i.e.
                HH:MM:00.999 return 0.

    See also:    SecondOfTheYear (458  ), SecondOfTheMonth (457  ), SecondOfTheWeek (457  ), SecondOfThe-
                Day (456  ), SecondOfTheHour (456  ), MilliSecondOfTheMinute (435  )


                Listing:  ./datutex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S e c o n d O f T h e M i n u t ef u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n(' S e c o n d o f  t h e  M i n u t e          :   ' ,S e c o n d O f T h e M i n u t(eN) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  M i n u t e :   ' ,
                                  M i l l i S e c o n d O f T h e M i n u(tNe) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.112          SecondOfTheMonth

    Synopsis:    Calculate number of seconds elapsed since the start of the month.

Declaration:     function  SecondOfTheMonth(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     SecondOfTheMonth returns the number of seconds that have passed since the start of the
                month  (00:00:00)  till  the  moment  indicated  by  AValue.  This  is  a  zero-based  number,  i.e.
                00:00:00.999 on the first day of the month will return 0.

                For an example, see the WeekOfTheMonth (471  ) function.

    See also:    WeekOfTheMonth (471  ),  DayOfTheMonth (404  ),  HourOfTheMonth (420  ),  MinuteOfThe-
                Month (440  ), MilliSecondOfTheMonth (436  )
                4.4.113          SecondOfTheWeek

    Synopsis:    Calculate the number of seconds elapsed since the start of the week

Declaration:     function  SecondOfTheWeek(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

                                                                                 457

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Description:     SecondOfTheWeek  returns  the  number  of  seconds  that  have  passed  since  the  start  of  the
                week  (00:00:00)  till  the  moment  indicated  by  AValue.   This  is  a  zero-based  number,  i.e.
                00:00:00.999 on the first day of the week will return 0.

                For an example, see the DayOfTheWeek (404  ) function.

    See also:    SecondOfTheYear (458  ), SecondOfTheMonth (457  ), SecondOfTheDay (456  ), SecondOfThe-
                Hour (456  ), SecondOfTheMinute (457  ), DayOfTheWeek (404  ), HourOfTheWeek (420  ), Min-
                uteOfTheWeek (440  ), MilliSecondOfTheWeek (436  )
                4.4.114          SecondOfTheYear

    Synopsis:    Calculate the number of seconds elapsed since the start of the year.

Declaration:     function  SecondOfTheYear(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     SecondOfTheYear returns the number of seconds that have passed since the start of the year
                (January 1, 00:00:00) till the moment indicated by AValue.  This is a zero-based number, i.e.
                January 1 00:00:00.999 will return 0.

                For an example, see the WeekOfTheYear (472  ) function.

    See also:    WeekOfTheYear  (472  ),  DayOfTheYear  (405  ),  HourOfTheYear  (420  ),  MinuteOfTheYear
                (440  ), SecondOfTheYear (458  ), MilliSecondOfTheYear (437  )
                4.4.115          SecondsBetween

    Synopsis:    Calculate the number of whole seconds between two DateTime values.

Declaration:     function  SecondsBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                        :  Int64

    Visibility:   default

Description:     SecondsBetween returns the number of whole seconds between ANow and AThen.  This means
                the fractional part of a second (milliseconds etc.)  is dropped.

    See also:    YearsBetween (484  ), MonthsBetween (443  ), WeeksBetween (473  ), DaysBetween (405  ), Hours-
                Between (420  ), MinutesBetween (441  ), MilliSecondsBetween (437  )


                Listing:  ./datutex/ex61.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S e c o n d s B e t w e e nf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  s e c o n d s b e t w e e n ' ) ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', S e c o n d s B e t w e e(nANow  ,AThen     ) ) ;
                end   ;


                Var



                                                                                 458

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(999*     O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(1001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(2001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(5001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.116          SecondSpan

    Synopsis:    Calculate the approximate number of seconds between two DateTime values.

Declaration:     function  SecondSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                 :  Double

    Visibility:   default

Description:     SecondSpan returns the number of seconds between ANow and AThen, including any fractional
                parts of a second.

    See also:    YearSpan (485  ), MonthSpan (444  ), WeekSpan (475  ), DaySpan (408  ), HourSpan (421  ), Min-
                uteSpan (442  ), MilliSecondSpan (438  ), SecondsBetween (458  )


                Listing:  ./datutex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S e c o n d S p a n f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  s e c o n d s b e t w e e n ' ) ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', S e c o n d S p a(nANow   ,AThen     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(999*     O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(1001*      O n e M i l l i S e c o n)d;
                                                                                 459

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(2001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(5001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.117          StartOfADay

    Synopsis:    Return the start of a day as a DateTime value, given a day indication

Declaration:     function  StartOfADay(const  AYear:  Word;const  AMonth:  Word;
                                                 const  ADay:  Word)  :  TDateTime;    Overload
                function  StartOfADay(const  AYear:  Word;const  ADayOfYear:  Word)
                                                   :  TDateTime;    Overload

    Visibility:   default

Description:     StartOfADay returns a TDateTime value with the date/time indication of the start (0:0:0.000)
                of the day given by AYear, AMonth, ADay.

                The day may also be indicated with a AYear, ADayOfYear pair.

    See also:    StartOfTheDay (462  ), StartOfTheWeek (463  ), StartOfAWeek (461  ), StartOfAMonth (461  ),
                StartOfTheMonth (463  ), EndOfTheWeek (418  ), EndOfAWeek (415  ), EndOfTheYear (418  ),
                EndOfAYear  (416  ),  EndOfTheMonth  (417  ),  EndOfAMonth  (415  ),  EndOfTheDay  (417  ),
                EndOfADay (414  )


                Listing:  ./datutex/ex38.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f A D a yf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" S t a r t  o f  t h e  day    :  " dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    Y ,M , D   :  Word   ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   M  := MonthOf     ( Today    ) ;
                    D := DayOf    ( Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A D a(yY ,M ,D  ) ) ) ;
                    DecodeDateDay          (Today    , Y ,D ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A D a(yY ,D ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                 460

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.118          StartOfAMonth

    Synopsis:    Return first date of month, given a year/month pair.

Declaration:     function  StartOfAMonth(const  AYear:  Word;const  AMonth:  Word)  :  TDateTime

    Visibility:   default

Description:     StartOfAMonth  e  returns  a  TDateTime  value  with  the  date  of  the  first  day  of  the  month
                indicated by the AYear, AMonth pair.

    See also:    StartOfTheMonth (463  ), EndOfTheMonth (417  ), EndOfAMonth (415  ), EndOfTheYear (418  ),
                EndOfAYear (416  ), StartOfAWeek (461  ), StartOfTheWeek (463  )


                Listing:  ./datutex/ex30.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f A M o n t hf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s month      :  " dd   mmmm     y y y y' ;
                Var
                    Y ,M   :  Word    ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   M  := MonthOf     ( Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A M o n t(hY,M  ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.119          StartOfAWeek

    Synopsis:    Return a day of the week, given a year, week and day in the week.

Declaration:     function  StartOfAWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                   const  ADayOfWeek:  Word)  :  TDateTime
                function  StartOfAWeek(const  AYear:  Word;const  AWeekOfYear:  Word)
                                                     :  TDateTime

    Visibility:   default

Description:     StartOfAWeek returns a TDateTime value with the date of the indicated day of the week
                indicated by the AYear, AWeek, ADayOfWeek values.

                The default value for ADayOfWeek is 1.

    See also:    StartOfTheWeek (463  ), EndOfTheWeek (418  ), EndOfAWeek (415  ), StartOfAMonth (461  ),
                EndOfTheYear (418  ), EndOfAYear (416  ), EndOfTheMonth (417  ), EndOfAMonth (415  )


                Listing:  ./datutex/ex34.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e StartOfAWeek           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;



                                                                                 461

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s week     :  " dd   mmmm     y y y y  hh  :nn  : s s' ;
                    Fmt2    =    '" S e c o n d day    o f  t h i s  week     :  " dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    Y ,W   :  Word    ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   W  := WeekOf     (Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,StartOfAWeek         (Y  ,W ) ) ) ;
                    W r i t e l n(FormatDateTime          ( Fmt2   , StartOfAWeek         (Y ,W  , 2 ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.120          StartOfAYear

    Synopsis:    Return the first day of a given year.

Declaration:     function  StartOfAYear(const  AYear:  Word)  :  TDateTime

    Visibility:   default

Description:     StartOfAYear returns a TDateTime value with the date of the first day of the year AYear
                (January 1).

    See also:    StartOfTheYear (464  ),  EndOfTheYear (418  ),  EndOfAYear (416  ),  EndOfTheMonth (417  ),
                EndOfAMonth (415  ), StartOfAWeek (461  ), StartOfTheWeek (463  )


                Listing:  ./datutex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f A Y e a rf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s y e a r  :  " dd   mmmm     y y y y ';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A Y e a(rY e a r O f(Today    ) ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.121          StartOfTheDay

    Synopsis:    Calculate the start of the day as a DateTime value, given a moment in the day.

Declaration:     function  StartOfTheDay(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     StartOfTheDay extracts the date part of  AValue and returns a TDateTime value with the
                date/time indication of the start (0:0:0.000) of this day.



                                                                                 462

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    See also:    StartOfADay  (460  ),  StartOfTheWeek  (463  ),  StartOfAWeek  (461  ),  StartOfAMonth  (461  ),
                StartOfTheMonth (463  ), EndOfTheWeek (418  ), EndOfAWeek (415  ), EndOfTheYear (418  ),
                EndOfAYear (416  ), EndOfTheMonth (417  ), EndOfAMonth (415  ), EndOftheDay (417  ), End-
                OfADay (414  )


                Listing:  ./datutex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f T h e D a yf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" S t a r t  o f  t h e  day    :  " dd  mmmm      y y y y hh  : nn : s s ';



                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f T h e D a(yToday   ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.122          StartOfTheMonth

    Synopsis:    Calculate the first day of the month, given a date in that month.

Declaration:     function  StartOfTheMonth(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     StartOfTheMonth extracts the year and month parts of  AValue and returns a TDateTime
                value  with  the  date  of  the  first  day  of  that  year  and  month  as  the  StartOfAMonth  (461  )
                function.

    See also:    StartOfAMonth  (461  ),  EndOfTheYear  (418  ),  EndOfAYear  (416  ),  EndOfTheMonth  (417  ),
                EndOfAMonth (415  ), StartOfAWeek (461  ), StartOfTheWeek (463  )


                Listing:  ./datutex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f T h e M o n t hf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s month      :  " dd   mmmm     y y y y' ;


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f T h e M o n t(hToday   ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.123          StartOfTheWeek

    Synopsis:    Return the first day of the week, given a date.

Declaration:     function  StartOfTheWeek(const  AValue:  TDateTime)  :  TDateTime



                                                                                 463

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    Visibility:  default

Description:     StartOfTheWeek extracts the year and week parts of AValue and returns a TDateTime value
                with the date of the first day of that week as the StartOfAWeek (461  ) function.

    See also:    StartOfAWeek  (461  ),  EndOfTheWeek  (418  ),  EndOfAWeek  (415  ),  StartOfAMonth  (461  ),
                EndOfTheYear (418  ), EndOfAYear (416  ), EndOfTheMonth (417  ), EndOfAMonth (415  )


                Listing:  ./datutex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e StartOfTheWeek             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s week     :  " dd   mmmm     y y y y ';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,StartOfTheWeek          ( Today    ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.124          StartOfTheYear

    Synopsis:    Return the first day of the year, given a date in this year.

Declaration:     function  StartOfTheYear(const  AValue:  TDateTime)  :  TDateTime

    Visibility:   default

Description:     StartOfTheYear extracts the year part of  AValue and returns a TDateTime value with the
                date of the first day of that year (January 1), as the StartOfAYear (462  ) function.

    See also:    StartOfAYear (462  ), EndOfTheYear (418  ), EndOfAYear (416  )


                Listing:  ./datutex/ex24.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f T h e Y e a rf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s y e a r  :  " dd   mmmm     y y y y ';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f T h e Y e a(rToday   ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.125          TimeOf

    Synopsis:    Extract the time part from a DateTime indication.

Declaration:     function  TimeOf(const  AValue:  TDateTime)  :  TDateTime



                                                                                 464

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    Visibility:  default

Description:     TimeOf extracts the time part from AValue and returns the result.

                Since the TDateTime is actually a double with the time part encoded in the fractional part,
                this operation corresponds to a call to Frac.

    See also:    DateOf (402  ), YearOf (483  ), MonthOf (443  ), DayOf (404  ), HourOf (419  ), MinuteOf (439  ),
                SecondOf (456  ), MilliSecondOf (434  )


                Listing:__./datutex/ex2.pp_________________________________________________________________________________________*
 *___________

                Program       Example2       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TimeOf       f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(' Time     i s  :  ' ,TimeToStr       ( TimeOf     (Now   ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.126          Today

    Synopsis:    Return the current date

Declaration:     function  Today  :  TDateTime

    Visibility:   default

Description:     Today is an alias for the Date (1401   ) function in the sysutils (1356   ) unit.

                For an example, see Yesterday (486  )

    See also:    #rtl.sysutils.Date (1401   ), Yesterday (486  ), Tomorrow (465  )
                4.4.127          Tomorrow

    Synopsis:    Return the next day

Declaration:     function  Tomorrow  :  TDateTime

    Visibility:   default

Description:     Tomorrow returns tomorrow's date.  Tomorrow is determined from the system clock, i.e.  it
                is Today (465  ) +1.

    See also:    Today (465  ), Yesterday (486  )


                Listing:__./datutex/ex19.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Tomorrow        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(FormatDateTime          ( ' T day      i s "  dd   mmmm     y y y y' ,Today    ) ) ;
                    W r i t e l n(FormatDateTime          ( ' T morrow         w i l l be  "  dd  mmmm      y y y y' ,Tomorrow    *
 *   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________
                                                                                 465

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.128          TryEncodeDateDay

    Synopsis:    Encode a year and day of year to a TDateTime value

Declaration:     function  TryEncodeDateDay(const  AYear:  Word;const  ADayOfYear:  Word;
                                                         var  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeDateDay encodes the values AYear and ADayOfYear to a date value and returns
                this value in AValue.

                If the encoding was succcesful, True is returned.  False is returned if any of the arguments
                is not valid.

    See also:    EncodeDateDay  (412  ),  EncodeDateTime  (413  ),  EncodeDateMonthWeek  (413  ),  Encode-
                DateWeek (413  ), TryEncodeDateTime (467  ), TryEncodeDateMonthWeek (466  ), TryEncode-
                DateWeek (468  )


                Listing:  ./datutex/ex84.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateDay              f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,DoY     :  Word   ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateDay          (Now   ,Y , DoY  ) ;
                    I f  TryEncodeDateDay            ( Y ,DoY   ,TS  )  then
                        W r i t e l n('Today      i s  :   ', DateToStr       (TS  ) )
                    e l s e
                        W r i t e l n('Wrong      y e a r/day    o f   y e a r  i n d i c a t i o'n) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.129          TryEncodeDateMonthWeek

    Synopsis:    Encode a year, month, week of month and day of week to a TDateTime value

Declaration:     function  TryEncodeDateMonthWeek(const  AYear:  Word;const  AMonth:  Word;
                                                                   const  AWeekOfMonth:  Word;
                                                                   const  ADayOfWeek:  Word;
                                                                   var  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeDateTime encodes the values AYearAMonth, WeekOfMonth,ADayOfWeek, to a date
                value and returns this value in AValue.

                If the encoding was succesful, True is returned, False if any of the arguments is not valid.

    See also:    DecodeDateMonthWeek  (410  ),  EncodeDateTime  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay (412  ), EncodeDateMonthWeek (413  ), TryEncodeDateTime (467  ), TryEncodeDate-
                Week (468  ), TryEncodeDateDay (466  ), NthDayOfWeek (445  )

                                                                                 466

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                Listing:  ./datutex/ex86.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateMonthWeek                   f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M ,Wom   , Dow    :  Word    ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateMonthWeek              (Now   ,Y  ,M ,WoM   ,DoW   ) ;
                    I f  TryEncodeDateMonthWeek                 (Y ,M  ,WoM   ,Dow   ,TS  )  then
                        W r i t e l n('Today      i s  :   ', DateToStr       (TS  ) )
                    e l s e
                        W r i t e l n('I n v a l i d y e a r/ month   / week   / dow    i n d i c a t i o n') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.130          TryEncodeDateTime

    Synopsis:    Encode  a  Year,  Month,  Day,  Hour,  minute,  seconds,  milliseconds  tuplet  to  a  TDateTime
                value

Declaration:     function  TryEncodeDateTime(const  AYear:  Word;const  AMonth:  Word;
                                                           const  ADay:  Word;const  AHour:  Word;
                                                           const  AMinute:  Word;const  ASecond:  Word;
                                                           const  AMilliSecond:  Word;
                                                           var  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     EncodeDateTime encodes the values AYearAMonth, ADay,AHour, AMinute,ASecond and AMilliSecond
                to a date/time valueand returns this value in AValue.

                If the date was encoded succesfully, True is returned, False is returned if one of the argu-
                ments is not valid.

    See also:    EncodeDateTime  (413  ),  EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  Encode-
                DateDay (412  ), TryEncodeDateDay (466  ), TryEncodeDateWeek (468  ), TryEncodeDateMon-
                thWeek (466  )


                Listing:  ./datutex/ex80.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateTime               f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,Mo  ,D  ,H ,Mi  , S ,MS    :  Word   ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateTime          ( Now   ,Y ,Mo  ,D  ,H , Mi , S ,MS  ) ;
                    I f  TryEncodeDateTime             (Y  ,Mo  ,D ,H  ,Mi  ,S , MS  ,TS  )  then



                                                                                 467

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                        W r i t e l n('Now    i s   :  ' ,DateTimeToStr          (TS  ) )
                    e l s e
                        W r i t e l n('Wrong      d a t e/t i m e  i n d i c a t i o n') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.131          TryEncodeDateWeek

    Synopsis:    Encode a year, week and day of week triplet to a TDateTime value

Declaration:     function  TryEncodeDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                           var  AValue:  TDateTime;const  ADayOfWeek:  Word)
                                                             :  Boolean
                function  TryEncodeDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                           var  AValue:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeDateWeek  encodes  the  values  AYear,  AWeekOfYear  and  ADayOfWeek  to  a  date
                value and returns this value in AValue.

                If the encoding was succcesful, True is returned.  False is returned if any of the arguments
                is not valid.

    See also:    EncodeDateMonthWeek  (413  ),  EncodeDateWeek  (413  ),  EncodeDateTime  (413  ),  Encode-
                DateDay (412  ), TryEncodeDateTime (467  ), TryEncodeDateMonthWeek (466  ), TryEncode-
                DateDay (466  )


                Listing:  ./datutex/ex82.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateWeek               f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,W , Dow    :  Word    ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateWeek          ( Now   ,Y ,W  ,Dow   ) ;
                    I f  TryEncodeDateWeek             (Y  ,W ,TS  ,Dow   )  then
                        W r i t e l n('Today      i s  :   ', DateToStr       (TS  ) )
                    e l s e
                        W r i t e l n('I n v a l i d d a t e/ week     i n d i c a t i o'n) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.132          TryEncodeDayOfWeekInMonth

    Synopsis:    Encode a year, month, week, day of week triplet to a TDateTime value

Declaration:     function  TryEncodeDayOfWeekInMonth(const  AYear:  Word;const  AMonth:  Word;
                                                                        const  ANthDayOfWeek:  Word;
                                                                        const  ADayOfWeek:  Word;
                                                                        var  AValue:  TDateTime)  :  Boolean
                                                                                 468

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    Visibility:  default

Description:     EncodeDayOfWeekInMonth  encodes  AYear,  AMonth,  ADayOfweek  and  ANthDayOfweek  to  a
                valid date stamp and returns the result in AValue.

                ANthDayOfweekis  the  N-th  time  that  this  weekday  occurs  in  the  month,  e.g.   the  third
                saturday of the month.

                The function returns True if the encoding was succesful, False if any of the values is not in
                range.

    See also:    NthDayOfWeek (445  ), EncodeDateMonthWeek (413  ), #rtl.sysutils.DayOfWeek (1405   ), De-
                codeDayOfWeekInMonth (412  ), EncodeDayOfWeekInMonth (414  )


                Listing:__./datutex/ex106.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 0 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDayOfWeekInMonth                   f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M ,NDoW    ,DoW     :  Word   ;
                    D   :  TDateTime       ;
                Begin
                    DecodeDayOfWeekInMonth                ( Date   ,Y  ,M ,NDoW    ,DoW   ) ;
                    I f  TryEncodeDayOfWeekInMonth                   (Y ,M  ,NDoW    ,DoW   ,D )  then
                        b e g i n
                       Write    ( DateToStr       (D ) , '  i s  t h e   ',NDow    , '- t h   ') ;
                        W r i t e l n(formatdateTime          ( 'dddd    ',D  ) ,'   o f  t h e  month    . ') ;
                       end
                    e l s e
                        W r i t e l n('I n v a l i d y e a r/ month   / NthDayOfweek           c o m b i n a t i o'n) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.133          TryJulianDateToDateTime

    Synopsis:    Convert a Julian date representation to a TDateTime value.

Declaration:     function  TryJulianDateToDateTime(const  AValue:  Double;
                                                                     var  ADateTime:  TDateTime)  :  Boolean

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (403  ),  JulianDateToDateTime  (434  ),  DateTimeToModifiedJulian-
                Date (403  ), TryModifiedJulianDateToDateTime (469  )
                4.4.134          TryModifiedJulianDateToDateTime

    Synopsis:    Convert a modified Julian date representation to a TDateTime value.

Declaration:     function  TryModifiedJulianDateToDateTime(const  AValue:  Double;
                                                                                  var  ADateTime:  TDateTime)
                                                                                    :  Boolean



                                                                                 469

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    Visibility:  default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (403  ),  JulianDateToDateTime  (434  ),  TryJulianDateToDateTime
                (469  ), DateTimeToModifiedJulianDate (403  ), ModifiedJulianDateToDateTime (442  )
                4.4.135          TryRecodeDateTime

    Synopsis:    Replace selected parts of a TDateTime value with other values

Declaration:     function  TryRecodeDateTime(const  AValue:  TDateTime;const  AYear:  Word;
                                                           const  AMonth:  Word;const  ADay:  Word;
                                                           const  AHour:  Word;const  AMinute:  Word;
                                                           const  ASecond:  Word;const  AMilliSecond:  Word;
                                                           var  AResult:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryRecodeDateTime  replaces  selected  parts  of  the  timestamp  AValue  with  the  date/time
                values  specified  in  AYear,  AMonth,  ADay,  AHour,  AMinute,  ASecond  and  AMilliSecond.  If
                any  of  these  values  equals  the  pre-defined  constant  RecodeLeaveFieldAsIs  (399  ),  then  the
                corresponding part of the date/time stamp is left untouched.

                The resulting date/time is returned in AValue.

                The function returns True if the encoding was succesful.  It returns False if one of the values
                AYear, AMonth, ADay, AHour, AMinute, ASecondAMilliSecond is not within a valid range.

    See also:    RecodeYear (452  ), RecodeMonth (450  ), RecodeDay (448  ), RecodeHour (448  ), RecodeMinute
                (450  ), RecodeSecond (451  ), RecodeMilliSecond (449  ), RecodeDate (446  ), RecodeTime (452  ),
                RecodeDateTime (447  )


                Listing:__./datutex/ex97.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 9 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryRecodeDateTime               f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;
                    D   :  TDateTime         ;


                Begin
                    I f  TryRecodeDateTime             (Now   , 2 0 0 0 , 2 ,R e c o d e L e a v e F i e l d A s,I0s, 0 , 0 , 0D,) *
 * then
                        b e g i n
                       S :=  FormatDateTime          ( Fmt  ,D  ) ;
                        W r i t e l n('T h i s  moment      i n   f e b r u a r i2 0 0 0  :   ',S  ) ;
                       end
                    e l s e
                        W r i t e l n('T h i s  moment      d i d/ d o e s  n o t  e x i s t i n   f e b r u a r i2 0 0 0' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                 470

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.136          UnixTimeStampToMac

    Synopsis:    Convert Unix Timestamp to a Mac Timestamp

Declaration:     function  UnixTimeStampToMac(const  AValue:  Int64)  :  Int64

    Visibility:   default

Description:     UnixTimeStampToMac  converts  the  unix  epoch  time  in  AValue  to  a  valid  Mac  timestamp
                indication and returns the result.

       Errors:   None.

    See also:    DateTimeToMac (403  ), MacToDateTime (434  ), MacTimeStampToUnix (434  )
                4.4.137          UnixToDateTime

    Synopsis:    Convert Unix epoch time to a TDateTime value

Declaration:     function  UnixToDateTime(const  AValue:  Int64)  :  TDateTime

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToUnix (404  )
                4.4.138          WeekOf

    Synopsis:    Extract week (of the year) from a given date.

Declaration:     function  WeekOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     WeekOf returns the week-of-the-year part of the AValue date/time indication.  It is a number
                between 1 and 53.

                For an example, see YearOf (483  )

    See also:    YearOf (483  ), DayOf (404  ), MonthOf (443  ), HourOf (419  ), MinuteOf (439  ), SecondOf (456  ),
                MilliSecondOf (434  )
                4.4.139          WeekOfTheMonth

    Synopsis:    Extract the week of the month (and optionally month and year) from a DateTime value

Declaration:     function  WeekOfTheMonth(const  AValue:  TDateTime)  :  Word;    Overload
                function  WeekOfTheMonth(const  AValue:  TDateTime;var  AYear:  Word;
                                                      var  AMonth:  Word)  :  Word;    Overload

    Visibility:   default

Description:     WeekOfTheMonth extracts the week of the month from Avalue and returns it, and optionally
                returns the year and month as well (in AYear, AMonth respectively).

 Remark:         Note that weeks are numbered from 1 using the ISO 8601 standard, and the day of the week
                as well.  This means that the year and month may not be the same as the year part of the
                date, since the week may start in the previous year as the first week of the year is the week
                with at least 4 days in it.



                                                                                 471

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    See also:    WeekOfTheYear  (472  ),  DayOfTheMonth  (404  ),  HourOfTheMonth  (420  ),  MinuteOfThe-
                Month (440  ), SecondOfTheMonth (457  ), MilliSecondOfTheMonth (436  )


                Listing:  ./datutex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e WeekOfTheMonth             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n('Week      o f  t h e Month                   :  ' ,WeekOfTheMonth           (N ) ) ;
                    W r i t e l n(' Day    o f  t h e  Month                    :  ' ,DayOfTheMonth          (N  ) ) ;
                    W r i t e l n(' Hour     o f  t h e Month                   :  ' ,HourOfTheMonth           (N ) ) ;
                    W r i t e l n(' M i n u t e o f  t h e  Month               :  ' ,MinuteOfTheMonth            (N  ) ) ;
                    W r i t e l n(' S e c o n d o f  t h e  Month               :  ' ,SecondOfTheMonth            (N  ) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  Month     :   ' ,
                                  M i l l i S e c o n d O f T h e M o n(tNh) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.140          WeekOfTheYear

    Synopsis:    Extract the week of the year (and optionally year) of a DateTime indication.

Declaration:     function  WeekOfTheYear(const  AValue:  TDateTime)  :  Word;    Overload
                function  WeekOfTheYear(const  AValue:  TDateTime;var  AYear:  Word)  :  Word
                                                     ;    Overload

    Visibility:   default

Description:     WeekOfTheYear extracts the week of the year from Avalue and returns it,  and optionally
                returns the year as well.  It returns the same value as WeekOf (471  ).

 Remark:         Note that weeks are numbered from 1 using the ISO 8601 standard, and the day of the week
                as well.  This means that the year may not be the same as the year part of the date, since
                the week may start in the previous year as the first week of the year is the week with at least
                4 days in it.

    See also:    WeekOf (471  ), MonthOfTheYear (443  ), DayOfTheYear (405  ), HourOfTheYear (420  ), Min-
                uteOfTheYear (440  ), SecondOfTheYear (458  ), MilliSecondOfTheYear (437  )


                Listing:  ./datutex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e WeekOfTheYear            f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin



                                                                                 472

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    N := Now   ;
                    W r i t e l n(' Month     o f  t h e  y e a r             :  ' ,MonthOfTheYear           (N  ) ) ;
                    W r i t e l n('Week      o f  t h e  y e a r              :  ' ,WeekOfTheYear          (N  ) ) ;
                    W r i t e l n(' Day    o f  t h e  y e a r                :  ' ,DayOfTheYear         ( N ) ) ;
                    W r i t e l n(' Hour     o f  t h e  y e a r              :  ' ,HourOfTheYear          (N  ) ) ;
                    W r i t e l n(' M i n u t e o f  t h e  y e a r           :  ' ,M i n u t e O f T h e Y e a(rN) ) ;
                    W r i t e l n(' S e c o n d o f  t h e  y e a r           :  ' ,S e c o n d O f T h e Y e a(rN) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  y e a r  :  ' ,
                                  M i l l i S e c o n d O f T h e Y e(aNr) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.141          WeeksBetween

    Synopsis:    Calculate the number of whole weeks between two DateTime values

Declaration:     function  WeeksBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                     :  Integer

    Visibility:   default

Description:     WeeksBetween returns the number of whole weeks between ANow and AThen.  This means
                the fractional part of a Week is dropped.

    See also:    YearsBetween (484  ), MonthsBetween (443  ), DaysBetween (405  ), HoursBetween (420  ), Min-
                utesBetween (441  ), SecondsBetween (458  ), MilliSecondsBetween (437  )


                Listing:  ./datutex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e WeeksBetween           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  w e e k s b e t w e e n  ') ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', WeeksBetween         (ANow   , AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -7;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -8;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -14;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -35;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -36;
                    T e s t(D1  , D2  ) ;
                                                                                 473

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    D2 :=  Today    -17;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.142          WeeksInAYear

    Synopsis:    Return the number of weeks in a given year

Declaration:     function  WeeksInAYear(const  AYear:  Word)  :  Word

    Visibility:   default

Description:     WeeksInAYear returns the number of weeks in the year AYear.  The return value is either
                52 or 53.

 Remark:         The first week of the year is determined according to the ISO 8601 standard:  It is the first
                week that has at least 4 days in it, i.e.  it includes a thursday.

    See also:    WeeksInYear (474  ), DaysInYear (408  ), DaysInAYear (407  ), DaysInMonth (407  ), DaysInA-
                Month (406  )


                Listing:  ./datutex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e WeeksInAYear           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y   :  Word   ;


                Begin
                    For    Y : = 1 9 9 2 t o  2 0 1 0  do
                        W r i t e l n(Y, '  h a s   ', WeeksInAYear         (Y ) , '  w e e k s. ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.143          WeeksInYear

    Synopsis:    return the number of weeks in the year, given a date

Declaration:     function  WeeksInYear(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     WeeksInYear returns the number of weeks in the year part of  AValue.  The return value is
                either 52 or 53.

 Remark:         The first week of the year is determined according to the ISO 8601 standard:  It is the first
                week that has at least 4 days in it, i.e.  it includes a thursday.

    See also:    WeeksInAYear  (474  ),  DaysInYear  (408  ),  DaysInAYear  (407  ),  DaysInMonth  (407  ),  DaysI-
                nAMonth (406  )


                Listing:  ./datutex/ex12.pp


                                                                                 474

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W e e k s I n Y e a rf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y   :  Word   ;


                Begin
                    For    Y : = 1 9 9 2 t o  2 0 1 0  do
                        W r i t e l n(Y, '  h a s   ', W e e k s I n Y e a(rEncodeDate       ( Y , 2 , 1 ) ) ,' w e e k s. ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.144          WeekSpan

    Synopsis:    Calculate the approximate number of weeks between two DateTime values.

Declaration:     function  WeekSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)  :  Double

    Visibility:   default

Description:     WeekSpan returns the number of weeks between ANow and AThen, including any fractional
                parts of a week.

    See also:    YearSpan  (485  ),  MonthSpan  (444  ),  DaySpan  (408  ),  HourSpan  (421  ),  MinuteSpan  (442  ),
                SecondSpan (459  ), MilliSecondSpan (438  ), WeeksBetween (473  )


                Listing:  ./datutex/ex65.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e WeekSpan        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  w e e k s b e t w e e n  ') ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', WeekSpan      (ANow    ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -7;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -8;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -14;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -35;
                    T e s t(D1  , D2  ) ;



                                                                                 475

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    D2 :=  Today    -36;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -17;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.145          WithinPastDays

    Synopsis:    Check whether two datetimes are only a number of days apart

Declaration:     function  WithinPastDays(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                      const  ADays:  Integer)  :  Boolean

    Visibility:   default

Description:     WithinPastDays compares the timestamps ANow and AThen and returns True if the differ-
                ence between them is at most ADays days apart, or False if they are further apart.

 Remark:         Since this function uses the DaysBetween (405  ) function to calculate the difference in days,
                this means that fractional days do not count, and the fractional part is simply dropped, so
                for two dates actually 2 and a half days apart, the result will also be True

    See also:    WithinPastYears (482  ), WithinPastMonths (480  ), WithinPastWeeks (481  ), WithinPastHours
                (477  ), WithinPastMinutes (479  ), WithinPastSeconds (480  ), WithinPastMilliSeconds (478  )


                Listing:  ./datutex/ex50.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t D a y sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  ADays      :   I n t e g e r) ;


                 b e g i n
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', ADays    , '  d a y s:   ') ;
                  W r i t e l n(W i t h i n P a s t D a y(sANow   ,AThen    ,ADays     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  Today    -23/24;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -1;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -25/24;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -26/24;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  Today    - 5 . 4 ;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  Today    - 2 . 5 ;
                    T e s t(D1  , D2  , 1 ) ;



                                                                                 476

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.146          WithinPastHours

    Synopsis:    Check whether two datetimes are only a number of hours apart

Declaration:     function  WithinPastHours(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                        const  AHours:  Int64)  :  Boolean

    Visibility:   default

Description:     WithinPastHours compares the timestamps ANow and AThen and returns True if the differ-
                ence between them is at most AHours hours apart, or False if they are further apart.

 Remark:         Since this function uses the HoursBetween (420  ) function to calculate the difference in Hours,
                this means that fractional hours do not count, and the fractional part is simply dropped, so
                for two dates actually 2 and a half hours apart, the result will also be True

    See also:    WithinPastYears  (482  ),  WithinPastMonths  (480  ),  WithinPastWeeks  (481  ),  WithinPast-
                Days  (476  ),  WithinPastMinutes  (479  ),  WithinPastSeconds  (480  ),  WithinPastMilliSeconds
                (478  )


                Listing:  ./datutex/ex51.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t H o u r sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  AHours       :  I n t e g e r) ;


                 b e g i n
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', AHours     ,'   h o u r s:  ' ) ;
                  W r i t e l n(W i t h i n P a s t H o u r(sANow  , AThen    ,AHours     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneMinute       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(61*    OneMinute       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(122*     OneMinute       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(306*     OneMinute       ) ;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  D1 - ( 5 . 4 *OneHour     ) ;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  D1 - ( 2 . 5 *OneHour     ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    T e s t(D1  , D2  , 2 ) ;



                                                                                 477

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.147          WithinPastMilliSeconds

    Synopsis:    Check whether two datetimes are only a number of milliseconds apart

Declaration:     function  WithinPastMilliSeconds(const  ANow:  TDateTime;
                                                                   const  AThen:  TDateTime;
                                                                   const  AMilliSeconds:  Int64)  :  Boolean

    Visibility:   default

Description:     WithinPastMilliSeconds compares the timestamps ANow and AThen and returns True if
                the difference between them is at most AMilliSeconds milliseconds apart, or False if they
                are further apart.

 Remark:         Since this function uses the MilliSecondsBetween (437  ) function to calculate the difference
                in milliseconds, this means that fractional milliseconds do not count, and the fractional part
                is simply dropped, so for two dates actually 2 and a half milliseconds apart, the result will
                also be True

    See also:    WithinPastYears  (482  ),  WithinPastMonths  (480  ),  WithinPastWeeks  (481  ),  WithinPast-
                Days (476  ), WithinPastHours (477  ), WithinPastMinutes (479  ), WithinPastSeconds (480  )


                Listing:__./datutex/ex54.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t M i l l i S e c o n dfsu n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;   A M i l l i S e c o n d s:  I n t e g e r) ;


                 b e g i n
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', A M i l l i S e c o n d,s'  m i l l i s e c o n d:s  ') ;
                  W r i t e l n(W i t h i n P a s t M i l l i S e c o n(dAsNow , AThen    , A M i l l i S e c o n d)s) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 - ( 0 . 9 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 - ( 1 . 0 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 - ( 1 . 1 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 - ( 2 . 5 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                 478

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.148          WithinPastMinutes

    Synopsis:    Check whether two datetimes are only a number of minutes apart

Declaration:     function  WithinPastMinutes(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                           const  AMinutes:  Int64)  :  Boolean

    Visibility:   default

Description:     WithinPastMinutes  compares  the  timestamps  ANow  and  AThen  and  returns  True  if  the
                difference  between  them  is  at  most  AMinutes  minutes  apart,  or  False  if  they  are  further
                apart.

 Remark:          Since  this  function  uses  the  MinutesBetween  (441  )  function  to  calculate  the  difference  in
                Minutes, this means that fractional minutes do not count, and the fractional part is simply
                dropped, so for two dates actually 2 and a half minutes apart, the result will also be True

    See also:    WithinPastYears  (482  ),  WithinPastMonths  (480  ),  WithinPastWeeks  (481  ),  WithinPast-
                Days (476  ), WithinPastHours (477  ), WithinPastSeconds (480  ), WithinPastMilliSeconds (478  )


                Listing:  ./datutex/ex52.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t M i n u t e sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  A M i n u t e s :   I n t e g e r) ;


                 b e g i n
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', AMinutes      , '  M i n u t e s:  ' ) ;
                  W r i t e l n(W i t h i n P a s t M i n u t e(sANow  ,AThen    , A M i n u t e s) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneSecond       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(61*    OneSecond       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(122*     OneSecond       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(306*     OneSecond       ) ;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  D1 - ( 5 . 4 *OneMinute       ) ;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  D1 - ( 2 . 5 *OneMinute       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                 479

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                4.4.149          WithinPastMonths

    Synopsis:    Check whether two datetimes are only a number of months apart

Declaration:     function  WithinPastMonths(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                         const  AMonths:  Integer)  :  Boolean

    Visibility:   default

Description:     WithinPastMonths compares the timestamps ANow and AThen and returns True if the dif-
                ference between them is at most AMonths months apart, or False if they are further apart.

 Remark:          Since  this  function  uses  the  MonthsBetween  (443  )  function  to  calculate  the  difference  in
                Months, this means that fractional months do not count, and the fractional part is simply
                dropped, so for two dates actually 2 and a half months apart, the result will also be True

    See also:    WithinPastYears (482  ), WithinPastWeeks (481  ), WithinPastDays (476  ), WithinPastHours
                (477  ), WithinPastMinutes (479  ), WithinPastSeconds (480  ), WithinPastMilliSeconds (478  )


                Listing:__./datutex/ex48.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 4 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t M o n t h sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  AMonths        :  I n t e g e r) ;


                 b e g i n
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', AMonths     , '  months     :   ') ;
                  W r i t e l n(W i t h i n P a s t M o n t h(sANow  ,AThen    , AMonths     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  , 1 2 ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  , 1 2 ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  , 1 2 ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  , 1 2 ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  , 1 1 ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  , 3 1 ) ;
                    T e s t(D1  , D2  , 3 2 ) ;
                    T e s t(D1  , D2  , 3 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.150          WithinPastSeconds

    Synopsis:    Check whether two datetimes are only a number of seconds apart



                                                                                 480

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Declaration:     function  WithinPastSeconds(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                          const  ASeconds:  Int64)  :  Boolean

    Visibility:  default

Description:     WithinPastSeconds  compares  the  timestamps  ANow  and  AThen  and  returns  True  if  the
                difference  between  them  is  at  most  ASeconds  seconds  apart,  or  False  if  they  are  further
                apart.

 Remark:         Since  this  function  uses  the  SecondsBetween  (458  )  function  to  calculate  the  difference  in
                seconds, this means that fractional seconds do not count, and the fractional part is simply
                dropped, so for two dates actually 2 and a half seconds apart, the result will also be True

    See also:    WithinPastYears  (482  ),  WithinPastMonths  (480  ),  WithinPastWeeks  (481  ),  WithinPast-
                Days (476  ), WithinPastHours (477  ), WithinPastMinutes (479  ), WithinPastMilliSeconds (478  )


                Listing:  ./datutex/ex53.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t S e c o n d sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  ASeconds        :   I n t e g e r) ;


                 b e g i n
                  Write    ( DateTimeToStr         ( AThen    ) , '  and    ' ,DateTimeToStr          (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', ASeconds      , '  s e c o n d s:  ' ) ;
                  W r i t e l n(W i t h i n P a s t S e c o n d(sANow  ,AThen    , ASeconds      ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(999*     O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(1001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(2001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  D1 -(5001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  D1 - ( 5 . 4 *OneSecond       ) ;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  D1 - ( 2 . 5 *OneSecond       ) ;
                    T e s t(D1  , D2  , 1 ) ;
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.151          WithinPastWeeks

    Synopsis:    Check whether two datetimes are only a number of weeks apart

                                                                                 481

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
Declaration:     function  WithinPastWeeks(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                       const  AWeeks:  Integer)  :  Boolean

    Visibility:  default

Description:     WithinPastWeeks compares the timestamps ANow and AThen and returns True if the differ-
                ence between them is at most AWeeks weeks apart, or False if they are further apart.

 Remark:         Since  this  function  uses  the  WeeksBetween  (473  )  function  to  calculate  the  difference  in
                Weeks,  this  means  that  fractional  Weeks  do  not  count,  and  the  fractional  part  is  simply
                dropped, so for two dates actually 2 and a half weeks apart, the result will also be True

    See also:    WithinPastYears (482  ), WithinPastMonths (480  ), WithinPastDays (476  ), WithinPastHours
                (477  ), WithinPastMinutes (479  ), WithinPastSeconds (480  ), WithinPastMilliSeconds (478  )


                Listing:  ./datutex/ex49.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t W e e k sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  AWeeks       :  I n t e g e r) ;


                 b e g i n
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', AWeeks     ,'   w e e k s:  ' ) ;
                  W r i t e l n(W i t h i n P a s t W e e k(sANow  , AThen    ,AWeeks     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -7;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -8;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -14;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -35;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  Today    -36;
                    T e s t(D1  , D2  , 5 ) ;
                    D2 :=  Today    -17;
                    T e s t(D1  , D2  , 1 ) ;
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.152          WithinPastYears

    Synopsis:    Check whether two datetimes are only a number of years apart

Declaration:     function  WithinPastYears(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                        const  AYears:  Integer)  :  Boolean



                                                                                 482

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    Visibility:  default

Description:     WithinPastYears compares the timestamps ANow and AThen and returns True if the differ-
                ence between them is at most AYears years apart, or False if they are further apart.

 Remark:        Since this function uses the YearsBetween (484  ) function to calculate the difference in years,
                this means that fractional years do not count, and the fractional part is simply dropped, so
                for two dates actually 2 and a half years apart, the result will also be True

    See also:    WithinPastMonths (480  ), WithinPastWeeks (481  ), WithinPastDays (476  ), WithinPastHours
                (477  ), WithinPastMinutes (479  ), WithinPastSeconds (480  ), WithinPastMilliSeconds (478  )


                Listing:__./datutex/ex47.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 4 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e W i t h i n P a s t Y e a r sf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ;  A Y e a r s  :  I n t e g e r) ;


                 b e g i n
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  Write    ( '  a r e  w i t h i n  ', AYears     ,'   y e a r s:  ' ) ;
                  W r i t e l n(W i t h i n P a s t Y e a r(sANow  , AThen    ,A Y e a r s) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  , 1 ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  , 1 ) ;
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.153          YearOf

    Synopsis:    Extract the year from a given date.

Declaration:     function  YearOf(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     YearOf returns the year part of the AValue date/time indication.  It is a number between 1
                and 9999.



                                                                                 483

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
    See also:    MonthOf  (443  ),  DayOf  (404  ),  WeekOf  (471  ),  HourOf  (419  ),  MinuteOf  (439  ),  SecondOf
                (456  ), MilliSecondOf (434  )


                Listing:  ./datutex/ex23.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Y e a r O f  f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    D   :  TDateTime       ;


                Begin
                    D := Now   ;
                    W r i t e l n(' Y e a r              :  ' , Y e a r O f(D ) ) ;
                    W r i t e l n(' Month                :  ' ,MonthOf      (D  ) ) ;
                    W r i t e l n(' Day                  :  ' ,DayOf    ( D ) ) ;
                    W r i t e l n('Week                  :  ' ,WeekOf     (D  ) ) ;
                    W r i t e l n(' Hour                 :  ' , HourOf    (D  ) ) ;
                    W r i t e l n(' M i n u t e          :  ' , M i n u t e O f(D) ) ;
                    W r i t e l n(' S e c o n d          :  ' , S e c o n d O f(D) ) ;
                    W r i t e l n(' M i l l i S e c o n d:  ' , M i l l i S e c o n d O(fD) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.154          YearsBetween

    Synopsis:    Calculate the number of whole years between two DateTime values

Declaration:     function  YearsBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                     :  Integer

    Visibility:   default

Description:     YearsBetween returns the number of whole years between ANow and AThen.  This number
                is an approximation, based on an average number of days of 365.25 per year (average over 4
                years).  This means the fractional part of a year is dropped.

    See also:    MonthsBetween (443  ), WeeksBetween (473  ), DaysBetween (405  ), HoursBetween (420  ), Min-
                utesBetween (441  ), SecondsBetween (458  ), MilliSecondsBetween (437  ), YearSpan (485  )


                Listing:  ./datutex/ex55.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Y e a r s B e t w e e nf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  y e a r s b e t w e e n  ') ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', Y e a r s B e t w e e(nANow  , AThen    ) ) ;
                end   ;



                                                                                 484

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.155          YearSpan

    Synopsis:    Calculate the approximate number of years between two DateTime values.

Declaration:     function  YearSpan(const  ANow:  TDateTime;const  AThen:  TDateTime)  :  Double

    Visibility:   default

Description:     YearSpan  returns  the  number  of  years  between  ANow  and  AThen,  including  any  fractional
                parts of a year.  This number is an approximation, based on an average number of days of
                365.25 per year (average over 4 years).

    See also:    MonthSpan  (444  ),  WeekSpan  (475  ),  DaySpan  (408  ),  HourSpan  (421  ),  MinuteSpan  (442  ),
                SecondSpan (459  ), MilliSecondSpan (438  ), YearsBetween (484  )


                Listing:  ./datutex/ex63.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Y e a r S p a n f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  y e a r s b e t w e e n  ') ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', Y e a r S p a n(ANow   ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                                                                                 485

                ______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                4.4.156          Yesterday

    Synopsis:    Return the previous day.

Declaration:     function  Yesterday  :  TDateTime

    Visibility:   default

Description:     Yesterday returns yesterday's date.  Yesterday is determined from the system clock, i.e.  it
                is Today (465  ) -1.

    See also:    Today (465  ), Tomorrow (465  )


                Listing:  ./datutex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Y e s t e r d a y f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    W r i t e l n(FormatDateTime          ( ' T day      i s  "   dd  mmmm      y y y y' ,Today    ) ) ;
                    W r i t e l n(FormatDateTime          ( ' " Y e s t e r d a ywas    "  dd   mmmm     y y y y ', Y e s t e r d a*
 * y) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________


                                                                                 486


Chapter   5


Reference   for   unit   'Dos'
5.1         System  information


Functions for retrieving and setting general system information such as date and time.



                                                        Table 5.1:

                  __Name__________________________Description________________________________________________
                    DosVersion (496  )            Get OS version
                    GetCBreak (502  )             Get setting of control-break handling flag
                    GetDate (502  )               Get system date
                    GetIntVec (505  )             Get interrupt vector status
                    GetTime (506  )               Get system time
                    GetVerify (507  )             Get verify flag
                    Intr (507  )                  Execute an interrupt
                    Keep (508  )                  Keep process in memory and exit
                    MSDos (508  )                 Execute MS-dos function call
                    PackTime (508  )              Pack time for file time
                    SetCBreak (509  )             Set control-break handling flag
                    SetDate (509  )               Set system date
                    SetIntVec (510  )             Set interrupt vectors
                    SetTime (511  )               Set system time
                    SetVerify (511  )             Set verify flag
                    SwapVectors (511  )           Swap interrupt vectors
                    UnPackTime (512  )            Unpack file time



5.2         Process  handling


Functions to handle process information and starting new processes.
5.3         Directory  and  disk  handling


Routines to handle disk information.

                                                             487

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________________________*
 *___

                                                        Table 5.2:

                  __Name__________________________Description_______________________________________________
                    DosExitCode (496  )           Exit code of last executed program
                    EnvCount (497  )              Return number of environment variables
                    EnvStr (498  )                Return environment string pair
                    Exec (498  )                  Execute program
                    GetEnv (503  )                Return specified environment string

                                                        Table 5.3:

                        _Name____________________Description____________________________________________
                          AddDisk (494  )         Add disk to list of disks (UNIX only)
                          DiskFree (494  )        Return size of free disk space
                          DiskSize (495  )        Return total disk size

5.4         File  handling


Routines to handle files on disk.



                                                        Table 5.4:

         __Name_____________________________Description______________________________________________________________
           FExpand (498  )                  Expand filename to full path
           FindClose (499  )                Close finfirst/findnext session
           FindFirst (499  )                Start find of file
           FindNext (500  )                 Find next file
           FSearch (500  )                  Search for file in a path
           FSplit (501  )                   Split filename in parts
           GetFAttr (503  )                 Return file attributes
           GetFTime (504  )                 Return file time
           GetLongName (505  )              Convert short filename to long filename (DOS only)
           GetShortName (506  )             Convert long filename to short filename (DOS only)
           SetFAttr (510  )                 Set file attributes
           SetFTime (510  )                 Set file time



5.5         File  open  mode  constants.


These constants are used in the Mode field of the TextRec record.  Gives information on the
filemode of the text I/O. For their definitions consult the following table:
5.6         File  attributes


The File Attribute constants are used in FindFirst (499  ), FindNext (500  ) to determine what
type of special file to search for in addition to normal files.  These flags are also used in the

                                                                 488

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________________________*
 *___

                                       Table 5.5:  Possible mode constants

                               __Constant_________Description_______________________Value______
                                 fmclosed         File is closed                   $D7B0
                                 fminput          File is read only                $D7B1
                                 fmoutput         File is write only               $D7B2
                                 fminout          File is read and write           $D7B3

SetFAttr (510  ) and GetFAttr (503  ) routines to set and retrieve attributes of files.  For their
definitions consult fileattributes (488  ).



                                        Table 5.6:  Possible file attributes

                             __Constant___________Description__________________________Value_____
                               readonly           Read-Only file attribute             $01
                               hidden             Hidden file attribute                $02
                               sysfile            System file attribute                $04
                               volumeid           Volumd ID file attribute             $08
                               directory          Directory file attribute             $10
                               archive            Archive file attribute               $20
                               anyfile            Match any file attribute             $3F



5.7         Used  units
                                       Table 5.7:  Used units by unit 'Dos'


                                                  __Name____________Page_____
                                                    baseunix          487



5.8         Overview


The DOS unit gives access to some operating system calls related to files, the file system, date
and time.  Except for the PalmOS target, this unit is available to all supported platforms.

The unit was first written for dos by Florian Klaempfl.  It was ported to linux by Mark May
and enhanced by Michael Van Canneyt.  The Amiga version was ported by Nils Sjoholm.

Under  non-DOS  systems,  some  of  the  functionality  is  lost,  as  it  is  either  impossible  or
meaningless to implement it.  Other than that, the functionality for all operating systems is
the same.
5.9         Constants,  types  and  variables



5.9.1        Constants

anyfile  =  $3F



                                                                 489

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________________________*
 *___
Match any file attribute


archive  =  $20


Archive file attribute


directory  =  $10


Directory file attribute


fauxiliary  =  $0010


CPU auxiliary flag.  Not used.


fcarry  =  $0001


CPU carry flag.  Not used.


FileNameLen  =  255


Maximum length of a filename


filerecnamelength  =  255


Maximum length of FileName part in FileRec (492  )


fmclosed  =  $D7B0


File is closed


fminout  =  $D7B3


File is read and write


fminput  =  $D7B1


File is read only


fmoutput  =  $D7B2


File is write only


foverflow  =  $0800


CPU overflow flag.  Not used.


fparity  =  $0004


CPU parity flag.  Not used.


fsign  =  $0080



                                                                 490

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________________________*
 *___
CPU sign flag.  Not used.


fzero  =  $0040


CPU zero flag.  Not used.


hidden  =  $02


Hidden file attribute


readonly  =  $01


Read-Only file attribute


sysfile  =  $04


System file attribute


TextRecBufSize  =  256


Size of default buffer in TextRec (493  )


TextRecNameLength  =  256


Maximum length of filename in TextRec (493  )


volumeid  =  $08


Volumd ID file attribute
5.9.2        Types

ComStr  =


Command-line string type


DateTime  =  packed  record
    Year  :  Word;
    Month  :  Word;
    Day  :  Word;
    Hour  :  Word;
    Min  :  Word;
    Sec  :  Word;
end
The DateTime type is used in PackTime (508  ) and UnPackTime (512  ) for setting/reading
file times with GetFTime (504  ) and SetFTime (510  ).


DirStr  =



                                                                 491

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________________________*
 *___
Full directory string type.


ExtStr  =


Filename extension string type.


FileRec  =  packed  record
   Handle  :  THandle;
   Mode  :  LongInt;
   RecSize  :  SizeInt;
   _private  :  Array[1..3*SizeOf(SizeInt)+5*SizeOf(pointer)]  of  Byte;
   UserData  :  Array[1..32]  of  Byte;
   name  :  Array[0..filerecnamelength]  of  Char;
end
FileRec is used for internal representation of typed and untyped files.


NameStr  =


Fill filename string type.


PathStr  =


Full File path string type.


Registers  =  packed  record
end
Record to keep CPU registers for MSDos (508  ) call.  Unused.


SearchRec  =  packed  record
   SearchPos  :  TOff;
   SearchNum  :  LongInt;
   DirPtr  :  Pointer;
   SearchType  :  Byte;
   SearchAttr  :  Byte;
   Mode  :  Word;
   Fill  :  Array[1..1]  of  Byte;
   Attr  :  Byte;
   Time  :  LongInt;
   Size  :  LongInt;
   Reserved  :  Word;
   Name  :  String;
   SearchSpec  :  String;
   NamePos  :  Word;
end
SearchRec  is  filled  by  the  FindFirst  (499  )  call  and  can  be  used  in  subsequent  FindNext
(500  ) calls to search for files.  The structure of this record depends on the platform.  Only
the following fields are present on all platforms:



                                                                 492

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________________________*
 *___
Attr    File attributes.

Time     File modification time.

Size   File size

Name      File name (name part only, no path)

Mode      File access mode (linux only)


TextBuf  =  Array[0..TextRecBufSize-1]  of  Char


Type for default buffer in TextRec (493  )


TextRec  =  packed  record
   Handle  :  THandle;
   Mode  :  LongInt;
   bufsize  :  SizeInt;
   _private  :  SizeInt;
   bufpos  :  SizeInt;
   bufend  :  SizeInt;
   bufptr  :  ^TextBuf;
   openfunc  :  pointer;
   inoutfunc  :  pointer;
   flushfunc  :  pointer;
   closefunc  :  pointer;
   UserData  :  Array[1..32]  of  Byte;
   name  :  Array[0..textrecnamelength-1]  of  Char;
   LineEnd  :  TLineEndStr;
   buffer  :  TextBuf;
end
TextRec describes the internal working of a Text file.

Remark  that  this  is  not  binary  compatible  with  the  Turbo  Pascal  definition  of  TextRec,
since the sizes of the different fields are different.


TLineEndStr  =


TLineEndStr is used in the TextRec (493  ) record to indicate the end-of-line sequence for a
text file.
5.9.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 :

Other values are possible, but are not documented.


                                                                 493

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________

                                                             Table 5.8:  Dos error codes

                                                         __Value______Meaning________________________
                                                           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.

                5.10          Procedures  and  functions



                5.10.1         AddDisk

    Synopsis:    Add disk definition to list if drives (Unix only)

Declaration:     function  AddDisk(const  path:  String)  :  Byte

    Visibility:   default

Description:     AddDisk adds a filename S to the internal list of disks.  It is implemented for systems which
                do not use DOS type drive letters.  This list is used to determine which disks to use in the
                DiskFree (494  ) and DiskSize (495  ) calls.  The DiskFree (494  ) and DiskSize (495  ) 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:

                      o'.'  for the current drive,

                      o'/fd0/.'  for the first floppy-drive (linux only).

                      o'/fd1/.'  for the second floppy-drive (linux only).

                      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 (494  ), DiskSize (495  )
                5.10.2         DiskFree

    Synopsis:    Get free size on Disk.

Declaration:     function  DiskFree(drive:  Byte)  :  Int64

    Visibility:   default

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.

 Remark:         For Unices:  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 :



                                                                                 494

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                      o'.'  for the current drive,

                      o'/fd0/.'  for the first floppy-drive (linux only).

                      o'/fd1/.'  for the second floppy-drive (linux only).

                      o'/' for the first hard disk.


                There is room for 1-26 drives.  You can add a drive with the AddDisk (494  ) 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:    DiskSize (495  ), AddDisk (494  )


                Listing:  ./dosex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;
                 u s e s Dos   ;


                {   Program       t o  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 ns i z e  h a s  ' ,D i s k S i z e( 0 ) ,'  b y t e s') ;
                    WriteLn     ( ' C u r r e n t l y' , D i s k F r e e( 0 ) ,' b y t e s  a r e  f r e e') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.3         DiskSize

    Synopsis:    Get total size of disk.

Declaration:     function  DiskSize(drive:  Byte)  :  Int64

    Visibility:   default

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.

 Remark:          For  unix  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 (linux only).

                      o'/fd1/.'  for the second floppy-drive (linux only).

                      o'/' for the first hard disk.


                There is room for 1-26 drives.  You can add a drive with the AddDisk (494  ) procedure.  These
                settings can be coded in dos.pp, in the initialization part.

                For an example, see DiskFree (494  ).

       Errors:   -1 when a failure occurs, or an invalid drive number is given.

    See also:    DiskFree (494  ), AddDisk (494  )
                                                                                 495

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.4         DosExitCode

    Synopsis:    Exit code of last executed program.

Declaration:     function  DosExitCode  :  Word

    Visibility:   default

Description:     DosExitCode contains (in the low byte) the exit-code of a program executed with the Exec
                call.

       Errors:   None.

    See also:    Exec (498  )


                Listing:  ./dosex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c  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      U n i x}
                    WriteLn     ( ' E x e c u t i n g/ b i n/ l s -  l a ') ;
                    E x e c( '/ b i n/ l s ' , '- l a' ) ;
                { $ELSE    }
                    WriteLn     ( ' E x e c u t i n gD i r ') ;
                    E x e c( GetEnv    ( 'COMSPEC      ' ) ,' /C   d i r ') ;
                { $ENDIF     }
                    WriteLn     ( ' Program       r e t u r n e dw i t h  E x i t C o d e ' ,Lo  (D o s E x i t C o d e) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.5         DosVersion

    Synopsis:    Current OS version

Declaration:     function  DosVersion  :  Word

    Visibility:   default

Description:     DosVersion  returns  the  operating  system  or  kernel  version.   The  low  byte  contains  the
                major version number, while the high byte contains the minor version number.

 Remark:         On systems where versions consists of more then two numbers, only the first two numbers
                will  be  returned.   For  example  Linux  version  2.1.76  will  give  you  DosVersion  2.1.   Some
                operating systems, such as FreeBSD, do not have system calls to return the kernel version,
                in that case a value of 0 will be returned.

       Errors:   None.


                Listing:  ./dosex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  D o s V e r s i o nf u n c t i o n.  }


                 v a r



                                                                                 496

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                    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     }
                {  $ i f d e fFreeBSD      }
                    OS :=  ' FreeBSD     ' ;
                { $ e n d i f}
                {  $ i f d e fNetBSD     }
                    OS :=  ' NetBSD     ';
                { $ e n d i f}
                {  $ i f d e f S o l a r i s}
                    OS :=  ' S o l a r i s';
                { $ e n d i f}
                {  $ i f d e fQNX   }
                    OS :=  'QNX   ' ;
                { $ e n d i f}


                { $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___.____________________________________________________________________________________________________________*
 *___________

                5.10.6         DTToUnixDate

    Synopsis:    Convert a DateTime to unix timestamp

Declaration:     function  DTToUnixDate(DT:  DateTime)  :  LongInt

    Visibility:   default

Description:     DTToUnixDate  converts  the  DateTime  value  in  DT  to  a  unix  timestamp.  It  is  an  internal
                function, implemented on Unix platforms, and should not be used.

       Errors:   None.

    See also:    UnixDateToDT (512  ), PackTime (508  ), UnpackTime (512  ), GetTime (506  ), SetTime (511  )
                5.10.7         EnvCount

    Synopsis:    Return the number of environment variables

Declaration:     function  EnvCount  :  LongInt

    Visibility:   default

Description:     EnvCount returns the number of environment variables.

       Errors:   None.

    See also:    EnvStr (498  ), GetEnv (503  )

                                                                                 497

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.8         EnvStr

    Synopsis:    Return environment variable by index

Declaration:     function  EnvStr(Index:  LongInt)  :  String

    Visibility:   default

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.

    See also:    EnvCount (497  ), GetEnv (503  )


                Listing:  ./dosex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;
                 u s e s Dos   ;


                {   Program       t o  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;
                 b e g i n
                    WriteLn     ( ' C u r r e n t E n v i r o n m e n ti s: ' ) ;
                    f o r  i : = 1  t o  EnvCount       do
                      WriteLn     ( E n v S t r(i ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.9         Exec

    Synopsis:    Execute another program, and wait for it to finish.

Declaration:     procedure  Exec(const  path:  PathStr;const  comline:  ComStr)

    Visibility:   default

Description:     Exec executes the program in Path, with the options given by ComLine.  The program name
                should  not  appear  again  in  ComLine,  it  is  specified  in  Path.   Comline  contains  only  the
                parameters that are passed to the program.

                After the program has terminated,  the procedure returns.  The Exit value of the program
                can be consulted with the DosExitCode function.

                For an example, see DosExitCode (496  )

       Errors:   Errors are reported in DosError.

    See also:    DosExitCode (496  )
                5.10.10          FExpand

    Synopsis:    Expand a relative path to an absolute path

Declaration:     function  FExpand(const  path:  PathStr)  :  PathStr

    Visibility:   default

                                                                                 498

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
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 or volume name
                (when supported).

 Remark:         On case sensitive file systems (such as unix and linux), the resulting name is left as it is,
                otherwise it is converted to uppercase.

       Errors:   FSplit (501  )


                Listing:__./dosex/ex11.pp__________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 1;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  FExpand       f u n c t i o n. }


                 b e g i n
                    WriteLn     ( ' Expanded       Name     o f   t h i s p r o g r a m i s   ', FExpand     ( ParamStr      ( 0 ) *
 *) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.11          FindClose

    Synopsis:    Dispose resources allocated by a FindFirst (499  )/FindNext (500  ) sequence.

Declaration:     procedure  FindClose(var  f:  SearchRec)

    Visibility:   default

Description:     FindClose frees any resources associated with the search record F.

                This call is needed to free any internal resources allocated by the FindFirst (499  ) or FindNext
                (500  ) calls.

                The  unix  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.

 Remark:         It is recommended to use the linux call Glob when looking for files on linux.

       Errors:   Errors are reported in DosError.

    See also:    FindFirst (499  ), FindNext (500  )
                5.10.12          FindFirst

    Synopsis:    Start search for one or more files.

Declaration:     procedure  FindFirst(const  path:  PathStr;attr:  Word;var  f:  SearchRec)

    Visibility:   default

Description:     FindFirst searches the file specified in Path.  Normal files, as well as all special files which
                have the attributes specified in Attr will be returned.

                It  returns  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).



                                                                                 499

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                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.

 Remark:         On  os/2,  you  cannot  issue  two  different  FindFirst  calls.   That  is,  you  must  close  any
                previous search operation with FindClose (499  ) before starting a new one.  Failure to do so
                will end in a Run-Time Error 6 (Invalid file handle)

       Errors:   Errors are reported in DosError.

    See also:    FindNext (500  ), FindClose (499  )


                Listing:  ./dosex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;
                 u s e s Dos   ;


                {   Program       t o  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 tf 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('* . * ' ,a r c h i v e,D i r) ;
                    WriteLn     ( ' F i l e N a m e'+S p a c e( 3 2 ) ,' F i l e S i z e': 9 ) ;
                    w h i l e ( D o s E r r o r=0)   do
                      b e g i n
                         W r i t e l n(D i r .Name   + S p a c e(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___.____________________________________________________________________________________________________________*
 *___________

                5.10.13          FindNext

    Synopsis:    Find next matching file after FindFirst (499  )

Declaration:     procedure  FindNext(var  f:  SearchRec)

    Visibility:   default

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.

                For an example, see FindFirst (499  ).

       Errors:   DosError is used to report errors.

    See also:    FindFirst (499  ), FindClose (499  )
                5.10.14          FSearch

    Synopsis:    Search a file in searchpath

Declaration:     function  FSearch(path:  PathStr;dirlist:  String)  :  PathStr

    Visibility:   default



                                                                                 500

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
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.  When
                no file is found, an empty string is returned.

 Remark:         On unix systems, DirList can also be separated by colons, as is customary on those envi-
                ronments.

       Errors:   None.

    See also:    FExpand (498  )


                Listing:  ./dosex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 1 0;


                 u s e s Dos   ;


                {   Program       t o  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: p a t h s t r;


                 b e g i n
                    s := F S e a r c h(ParamStr      ( 1 ) ,GetEnv     ( 'PATH   ' ) ) ;
                    i f  s=  ' '  then
                       WriteLn      (ParamStr       ( 1 ) ,'  n o t  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___.____________________________________________________________________________________________________________*
 *___________

                5.10.15          FSplit

    Synopsis:    Split a full-path filename in parts.

Declaration:     procedure  FSplit(path:  PathStr;var  dir:  DirStr;var  name:  NameStr;
                                           var  ext:  ExtStr)

    Visibility:   default

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 (.).  For dos, however, an exception is
                made when LFNSupport=False, then the extension is defined as all characters after the first
                dot.

       Errors:   None.

    See also:    FSearch (500  )


                Listing:  ./dosex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 1 2;


                 u s e s Dos   ;


                {   Program       t o  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  d i r: d i r s t r;
                       name    :n a m e s t r;
                        e x t: e x t s t r;



                                                                                 501

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________


                 b e g i n
                    F S p l i t(ParamStr      ( 1 ) ,d i r ,name   , e x t) ;
                    WriteLn     ( ' S p l i t t e d ', ParamStr      ( 1 ) ,'  i n : ') ;
                    WriteLn     ( ' Path            :  ' , d i r) ;
                    WriteLn     ( 'Name             :  ' ,name    ) ;
                    WriteLn     ( ' E x t e n s i o n: ' ,e x t ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.16          GetCBreak

    Synopsis:    Get control-Break flag

Declaration:     procedure  GetCBreak(var  breakvalue:  Boolean)

    Visibility:   default

Description:     GetCBreak gets the status of CTRL-Break checking under dos and Amiga.  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.

 Remark:         Under non-dos and non-Amiga operating systems, BreakValue always returns True.

       Errors:   None

    See also:    SetCBreak (509  )
                5.10.17          GetDate

    Synopsis:    Get the current date

Declaration:     procedure  GetDate(var  year:  Word;var  month:  Word;var  mday:  Word;
                                            var  wday:  Word)

    Visibility:   default

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 (506  ), SetDate (509  )


                Listing:  ./dosex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  G e t D a t e f u n c t i o n. }


                 c o n s t
                    D a y S t r:a r r a y[ 0 . . 6 ] o f   s t r i n g[ 3 ] = ('Sun  ' ,'Mon   ' , 'Tue   ' ,'Wed   ' , 'Thu   ', '*
 * F r i' , 'S a t ') ;
                    MonthStr      : a r r a y[ 1 . . 1 2 ]o f   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
                    G e t D a t e(Year   ,Month     ,Day   ,WDay   ) ;



                                                                                 502

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                    WriteLn     ( ' C u r r e n t d a t e' ) ;
                    WriteLn     ( D a y S t r[WDay   ] , ' ,  ' ,Day   , '  ' ,MonthStr      [ Month    ] , '  ' ,Year   , ' . ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.18          GetEnv

    Synopsis:    Get environment variable by name.

Declaration:     function  GetEnv(envvar:  String)  :  String

    Visibility:   default

Description:     Getenv returns the value of the environment variable EnvVar.  When there is no environment
                variable EnvVar defined, an empty string is returned.

 Remark:         Under some operating systems (such as unix), case is important when looking for EnvVar.

       Errors:   None.

    See also:    EnvCount (497  ), EnvStr (498  )


                Listing:  ./dosex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;
                 u s e s Dos   ;


                {   Program       t o  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 tPATH      i s  ' ,GetEnv     ( 'PATH   ' ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.19          GetFAttr

    Synopsis:    Get file attributes

Declaration:     procedure  GetFAttr(var  f;var  attr:  Word)

    Visibility:   default

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

                      oHidden

                      oSysFile

                      oVolumeId

                      oDirectory

                      oArchive


                Under linux, supported attributes are:


                      oDirectory

                      oReadOnly if the current process doesn't have access to the file.



                                                                                 503

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                      oHidden for files whose name starts with a dot ('.').


       Errors:   Errors are reported in DosError

    See also:    SetFAttr (510  )


                Listing:  ./dosex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;
                 u s e s Dos   ;


                {   Program       t o  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. }


                 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 ) ,'  h a s   a t t r i b u t e' ,A t t r) ;
                    i f  ( A t t r  and    a r c h i v e)<>0    then    WriteLn      ( '-   A r c h i v e') ;
                    i f  ( A t t r  and    d i r e c t o r)y<>0    then     WriteLn     ( '-   D i r e c t o r y') ;
                    i f  ( A t t r  and    r e a d o n l)y<>0    then     WriteLn     ( ' -  Read   - O n l y' ) ;
                    i f  ( A t t r  and    s y s f i l e)<>0    then    WriteLn      ( '-  System     ' ) ;
                    i f  ( A t t r  and    h i d d e n)<>0    then    WriteLn      ( '-   H i d d e n') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.20          GetFTime

    Synopsis:    Get file last modification time.

Declaration:     procedure  GetFTime(var  f;var  time:  LongInt)

    Visibility:   default

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 (510  ), PackTime (508  ), UnPackTime (512  )


                Listing:  ./dosex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;
                 u s e s Dos   ;


                {   Program       t o  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 ;



                                                                                 504

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                end   ;


                 v a r
                    f        :  F i l e;
                    Time     :  L o n g i n t;
                    DT       :  DateTime      ;
                 b e g i n
                    i f  Paramcount        >0   then
                        A s s i g n(f ,ParamStr      ( 1 ) )
                    e l s e
                        A s s i g n(f , 'e x 9. pp  '  ) ;
                    R e s e t( 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 don    ') ;
                    W r i t e l n ( L0 (DT   .Month    ) , '- ' ,L0  (DT  . Day  ) , '- ' ,DT  . Year   ,
                                    '  a t   ' ,L0 ( DT  .Hour   ) , ' : ', L0 ( DT  .Min   ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.21          GetIntVec

    Synopsis:    Get interrupt vector

Declaration:     procedure  GetIntVec(intno:  Byte;var  vector:  pointer)

    Visibility:   default

Description:     GetIntVec returns the address of interrupt vector IntNo.

 Remark:         This call does nothing,  it is present for compatibility only.  Modern systems do not allow
                low level access to the hardware.

       Errors:   None.

    See also:    SetIntVec (510  )
                5.10.22          GetLongName

    Synopsis:    Get the long filename of a DOS 8.3 filename.

Declaration:     function  GetLongName(var  p:  String)  :  Boolean

    Visibility:   default

Description:     This function is only implemented in the GO32V2 and Win32 versions of Free Pascal.

                GetLongName changes the filename p to a long filename if the API 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 API call was successful, False otherwise.

                This  function  should  only  be  necessary  when  using  the  DOS  extender  under  Windows  95
                and higher.

       Errors:   If the API call was not succesfull, False is returned.

    See also:    GetShortName (506  )


                                                                                 505

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.23          GetMsCount

    Synopsis:    Number of milliseconds since a starting point.

Declaration:     function  GetMsCount  :  Int64

    Visibility:   default

Description:     GetMSCount returns a number of milliseconds elapsed since a certain moment in time.  This
                moment  in  time  is  implementation  dependent.  This  function  is  used  for  timing  purposes:
                Substracting the results of 2 subsequent calls to this function returns the number of millisec-
                onds elapsed between the two calls.

                This call is not very reliable, it is recommended to use some system specific calls for timings.

    See also:    GetTime (506  )
                5.10.24          GetShortName

    Synopsis:    Get the short (8.3) filename of a long filename.

Declaration:     function  GetShortName(var  p:  String)  :  Boolean

    Visibility:   default

Description:     This function is only implemented in the GO32V2 and Win32 versions of Free Pascal.

                GetShortName changes the filename p to a short filename if the API 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 API call was successful, False otherwise.

                This  function  should  only  be  necessary  when  using  the  DOS  extender  under  Windows  95
                and higher.

       Errors:   If the API call was not successful, False is returned.

    See also:    GetLongName (505  )
                5.10.25          GetTime

    Synopsis:    Return the current time

Declaration:     procedure  GetTime(var  hour:  Word;var  minute:  Word;var  second:  Word;
                                            var  sec100:  Word)

    Visibility:   default

Description:     GetTime returns the system's time.  Hour is a on a 24-hour time scale.  sec100 is in hundredth
                of a second.

 Remark:         Certain operating systems (such as Amiga), always set the sec100 field to zero.

       Errors:   None.

    See also:    GetDate (502  ), SetTime (511  )


                Listing:  ./dosex/ex3.pp

                                                                                 506

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;
                 u s e s Dos   ;


                {   Program       t o  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  ( S e c) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.26          GetVerify

    Synopsis:    Get verify flag

Declaration:     procedure  GetVerify(var  verify:  Boolean)

    Visibility:   default

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.

 Remark:         Under non-dos systems (excluding os/2 applications running under vanilla DOS), Verify is
                always True.

       Errors:   None.

    See also:    SetVerify (511  )
                5.10.27          Intr

    Synopsis:    Execute interrupt

Declaration:     procedure  Intr(intno:  Byte;var  regs:  Registers)

    Visibility:   default

Description:     Intr executes a software interrupt number IntNo (must be between 0 and 255), with pro-
                cessor  registers  set  to  Regs.   After  the  interrupt  call  returned,  the  processor  registers  are
                saved in Regs.

 Remark:         Under non-dos operating systems, this call does nothing.

       Errors:   None.

    See also:    MSDos (508  )



                                                                                 507

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.28          Keep

    Synopsis:    Terminate and stay resident.

Declaration:     procedure  Keep(exitcode:  Word)

    Visibility:   default

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.

 Remark:         This call does nothing, it is present for compatibility only.

       Errors:   None.
                5.10.29          MSDos

    Synopsis:    Execute MS-DOS system call

Declaration:     procedure  MSDos(var  regs:  Registers)

    Visibility:   default

Description:     MSDos executes an operating system call.  This is the same as doing a Intr call with the
                interrupt number for an os call.

 Remark:          Under  non-dos  operating  systems,  this  call  does  nothing.   On  DOS  systems,  this  calls
                interrupt $21.

       Errors:   None.

    See also:    Intr (507  )
                5.10.30          PackTime

    Synopsis:    Pack DateTime value to a packed-time format.

Declaration:     procedure  PackTime(var  t:  DateTime;var  p:  LongInt)

    Visibility:   default

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 (510  ), FindFirst (499  ), FindNext (500  ), UnPackTime (512  )


                Listing:  ./dosex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;
                 u s e s Dos   ;


                {   Program       t o  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
                    w i t h DT    do



                                                                                 508

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                      b e g i n
                         Y e a r: = 1 9 9 8 ;
                         Month    : = 1 1 ;
                         Day   : = 1 1 ;
                         Hour   : = 1 1 ;
                         Min   : = 1 1 ;
                         S e c : = 1 1 ;
                      end  ;
                    PackTime      (DT  , Time   ) ;
                    WriteLn     ( ' Packed      Time     :  ' ,Time    ) ;
                    UnPackTime       ( Time   ,DT   ) ;
                    WriteLn     ( ' Unpacked       A g a i n: ' ) ;
                    w i t h DT    do
                      b e g i n
                         WriteLn     (  'Y e a r    ', Y e a r) ;
                         WriteLn     (  'Month      ', Month    ) ;
                         WriteLn     (  'Day        ', Day  ) ;
                         WriteLn     (  'Hour       ', Hour   ) ;
                         WriteLn     (  'Min        ', Min  ) ;
                         WriteLn     (  'S e c      ', S e c) ;
                      end  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                5.10.31          SetCBreak

    Synopsis:    Set Control-Break flag status

Declaration:     procedure  SetCBreak(breakvalue:  Boolean)

    Visibility:   default

Description:     SetCBreak sets the status of CTRL-Break checking.  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.

 Remark:         Under non-dos and non-Amiga operating systems, this call does nothing.

       Errors:   None.

    See also:    GetCBreak (502  )
                5.10.32          SetDate

    Synopsis:    Set system date

Declaration:     procedure  SetDate(year:  Word;month:  Word;day:  Word)

    Visibility:   default

Description:     SetDate sets the system's internal date.  Year is a number between 1980 and 2099.

 Remark:         On a unix machine, there must be root privileges, otherwise this routine will do nothing.
                On other unix systems, this call currently does nothing.

       Errors:   None.

    See also:    GetDate (502  ), SetTime (511  )


                                                                                 509

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.33          SetFAttr

    Synopsis:    Set file attributes

Declaration:     procedure  SetFAttr(var  f;attr:  Word)

    Visibility:   default

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

                      oHidden

                      oSysFile

                      oVolumeId

                      oDirectory

                      oArchive


 Remark:         Under unix like systems (such as linux and BeOS) the call exists, but is not implemented,
                i.e.  it does nothing.

       Errors:   Errors are reported in DosError.

    See also:    GetFAttr (503  )
                5.10.34          SetFTime

    Synopsis:    Set file modification time.

Declaration:     procedure  SetFTime(var  f;time:  LongInt)

    Visibility:   default

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.

 Remark:         Under unix like systems (such as linux and BeOS) the call exists, but is not implemented,
                i.e.  it does nothing.

       Errors:   Errors are reported in DosError

    See also:    GetFTime (504  ), PackTime (508  ), UnPackTime (512  )
                5.10.35          SetIntVec

    Synopsis:    Set interrupt vector

Declaration:     procedure  SetIntVec(intno:  Byte;vector:  pointer)

    Visibility:   default

Description:     SetIntVec  sets  interrupt  vector  IntNo  to  Vector.   Vector  should  point  to  an  interrupt
                procedure.

 Remark:         This call does nothing, it is present for compatibility only.

       Errors:   None.

    See also:    GetIntVec (505  )



                                                                                 510

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.36          SetTime

    Synopsis:    Set system time

Declaration:     procedure  SetTime(hour:  Word;minute:  Word;second:  Word;sec100:  Word)

    Visibility:   default

Description:     SetTime sets the system's internal clock.  The Hour parameter is on a 24-hour time scale.

 Remark:         On a linux machine, there must be root privileges, otherwise this routine will do nothing.
                On other unix systems, this call currently does nothing.

       Errors:   None.

    See also:    GetTime (506  ), SetDate (509  )
                5.10.37          SetVerify

    Synopsis:    Set verify flag

Declaration:     procedure  SetVerify(verify:  Boolean)

    Visibility:   default

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.

 Remark:         Under non-dos operating systems (excluding os/2 applications running under vanilla dos),
                Verify is always True.

       Errors:   None.

    See also:    SetVerify (511  )
                5.10.38          SwapVectors

    Synopsis:    Swap interrupt vectors

Declaration:     procedure  SwapVectors

    Visibility:   default

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.

 Remark:         Under certain operating systems, this routine may be implemented as an empty stub.

       Errors:   None.

    See also:    Exec (498  ), SetIntVec (510  )


                                                                                 511

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'DOS'____________*
 *___________________
                5.10.39          UnixDateToDt

    Synopsis:    Convert a unix timestamp to a DateTime record

Declaration:     procedure  UnixDateToDt(SecsPast:  LongInt;var  Dt:  DateTime)

    Visibility:   default

Description:     DTToUnixDate converts the unix timestamp value in SecsPast to a DateTime representation
                in DT. It is an internal function, implemented on Unix platforms, and should not be used.

       Errors:   None.

    See also:    DTToUnixDate (497  ), PackTime (508  ), UnpackTime (512  ), GetTime (506  ), SetTime (511  )
                5.10.40          UnpackTime

    Synopsis:    Unpack packed file time to a DateTime value

Declaration:     procedure  UnpackTime(p:  LongInt;var  t:  DateTime)

    Visibility:   default

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.

                For an example, see PackTime (508  ).

       Errors:   None.

    See also:    GetFTime (504  ), FindFirst (499  ), FindNext (500  ), PackTime (508  )
                5.10.41          weekday

    Synopsis:    Return the day of the week

Declaration:     function  weekday(y:  LongInt;m:  LongInt;d:  LongInt)  :  LongInt

    Visibility:   default

Description:     WeekDay returns the day of the week on which the day Y/M/D falls.  Sunday is represented
                by 0, Saturday is 6.

       Errors:   On error, -1 is returned.

    See also:    PackTime (508  ), UnpackTime (512  ), GetTime (506  ), SetTime (511  )


                                                                                 512


                Chapter   6


                Reference   for   unit   'dxeload'
                6.1         Overview


                The dxeload unit was implemented by Pierre Mueller 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.
                6.2         Procedures  and  functions



                6.2.1        dxe__load

    Synopsis:    Load DXE file in memory

Declaration:     function  dxe_load(filename:  String)  :  pointer

    Visibility:   default

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.

                For an example, see the emu387 (517  ) unit in the RTL.

       Errors:   If an error occurs during the load or relocations, Nil is returned.



                                                                             513


Chapter   7


Reference   for   unit   'dynlibs'
7.1         Overview


The Dynlibs unit provides support for dynamically loading shared libraries.  It is available
only on those platforms that support shared libraries.  The functionality available here may
only  be  a  part  of  the  functionality  available  on  each  separate  platform,  in  the  interest  of
portability.

On unix platforms, using this unit will cause the program to be linked to the C library, as
most shared libraries are implemented in C and the dynamical linker too.
7.2         Constants,  types  and  variables



7.2.1        Constants

NilHandle  =  TLibHandle  (  0  )


Correctly typed Nil handle - returned on error by LoadLibrary (515  )


SharedSuffix  =  'so'

7.2.2        Types

HModule  =  TLibHandle


Alias for TLibHandle (514  ) type.


TLibHandle  =  PtrInt


TLibHandle should be considered an opaque type.  It is defined differently on various plat-
forms.  The definition shown here depends on the platform for which the documentation was
generated.


                                                             514

                __________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DYNLIBS'________________*
 *___________________
                7.3         Procedures  and  functions



                7.3.1        FreeLibrary

    Synopsis:    For compatibility with Delphi/Windows:  Unload a library

Declaration:     function  FreeLibrary(Lib:  TLibHandle)  :  Boolean

    Visibility:   default

Description:     FreeLibrary provides the same functionality as UnloadLibrary (516  ), and is provided for
                compatibility with Delphi.

    See also:    UnloadLibrary (516  )
                7.3.2        GetProcAddress

    Synopsis:    For compatibility with Delphi/Windows:  Get the address of a procedure

Declaration:     function  GetProcAddress(Lib:  TLibHandle;ProcName:  AnsiString)  :  Pointer

    Visibility:   default

Description:     GetProcAddress  provides  the  same  functionality  as  GetProcedureAddress  (515  ),  and  is
                provided for compatibility with Delphi.

    See also:    GetProcedureAddress (515  )
                7.3.3        GetProcedureAddress

    Synopsis:    Get the address of a procedure or symbol in a dynamic library.

Declaration:     function  GetProcedureAddress(Lib:  TLibHandle;ProcName:  AnsiString)
                                                                :  Pointer

    Visibility:   default

Description:     GetProcedureAddress returns a pointer to the location in memory of the symbol ProcName
                in the dynamically loaded library specified by it's handle lib.  If the symbol cannot be found
                or the handle is invalid, Nil is returned.

                On Windows,  only an exported procedure or function can be searched this way.  On Unix
                platforms the location of any exported symbol can be retrieved this way.

       Errors:   If the symbol cannot be found, Nil is returned.

    See also:    LoadLibrary (515  ), UnLoadLibrary (516  )
                7.3.4        LoadLibrary

    Synopsis:    Load a dynamic library and return a handle to it.

Declaration:     function  LoadLibrary(Name:  AnsiString)  :  TLibHandle

    Visibility:   default

                                                                                 515

                __________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DYNLIBS'________________*
 *___________________
Description:     LoadLibrary loads a dynamic library in file Name and returns a handle to it.  If the library
                cannot be loaded, NilHandle (514  ) is returned.

                No assumptions should be made about the location of the loaded library if a relative path-
                name is specified.  The behaviour is dependent on the platform.  Therefore it is best to specify
                an absolute pathname if possible.

       Errors:   On error, NilHandle (514  ) is returned.

    See also:    UnloadLibrary (516  ), GetProcedureAddress (515  )
                7.3.5        SafeLoadLibrary

    Synopsis:    Saves the control word and loads a library

Declaration:     function  SafeLoadLibrary(Name:  AnsiString)  :  TLibHandle

    Visibility:   default

Description:     SafeLoadLibary  saves  the  FPU  control  word,  and  calls  LoadLibrary  (515  )  with  library
                name Name.  After that function has returned, the FPU control word is saved again.  (only
                on Intel i386 CPUS).

    See also:    LoadLibrary (515  )
                7.3.6        UnloadLibrary

    Synopsis:    Unload a previously loaded library

Declaration:     function  UnloadLibrary(Lib:  TLibHandle)  :  Boolean

    Visibility:   default

Description:     UnloadLibrary unloads a previously loaded library (specified by the handle lib).  The call
                returns True if succesful, False otherwisa.

       Errors:   On error, False is returned.

    See also:    LoadLibrary (515  ), GetProcedureAddress (515  )



                                                                                 516


                Chapter   8


                Reference   for   unit   'emu387'
                8.1         Overview


                The emu387 unit was written by Pierre Mueller 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.
                8.2         Procedures  and  functions



                8.2.1        npxsetup

    Synopsis:    Set up coprocessor emulation.

Declaration:     procedure  npxsetup(prog_name:  String)

    Visibility:   default

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.


                                                                             517

         ____________________________________________________________CHAPTER_8.___REFERENCE_FOR_UNIT_'EMU387'______________________*
 *____________
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.


                                                                          518


Chapter   9


Reference   for   unit   'getopts'
9.1         Overview


This document describes the GETOPTS unit for Free Pascal.  It was written for linux by
Michael 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.
9.2         Constants,  types  and  variables



9.2.1        Constants

EndOfOptions  =  #255


Returned by getopt (521  ),getlongopts (521  ) to indicate that there are no more options.


No_Argument  =  0


Specifies that a long option does not take an argument.


Optional_Argument  =  2


Specifies that a long option optionally takes an argument.


OptSpecifier  :  Set  of  Char  =  ['-']


Character indicating an option on the command-line.


Required_Argument  =  1


Specifies that a long option needs an argument.



                                                             519

_________________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'GETOPTS'_________________________________*
 *___

                            Table 9.1:  Enumeration values for type Orderings


            __Value___________________Explanation__________________________________________________________________
              permute                  Change command-line options.
              require_order            Don't touch the ordering of the command-line options
              return_in_order          Return options in the correct order.

9.2.2        Types

Orderings  =  (require_order,permute,return_in_order)


Command-line ordering options.


POption  =  ^TOption


Pointer to TOption (520  ) record.


TOption  =  record
    Name  :  String;
    Has_arg  :  Integer;
    Flag  :  PChar;
    Value  :  Char;
end
The TOption type is used to communicate the long options to GetLongOpts (521  ).  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.
9.2.3        Variables

OptArg  :  String


Set to the argument of an option, if the option needs one.


OptErr  :  Boolean


Indicates whether getopt() prints error messages.


OptInd  :  LongInt


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.


OptOpt  :  Char


In case of an error, contains the character causing the error.
                                                                 520

                _________________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'GETOPTS'_________________*
 *___________________
                9.3         Procedures  and  functions



                9.3.1        GetLongOpts

    Synopsis:    Return next long option.

Declaration:     function  GetLongOpts(ShortOpts:  String;LongOpts:  POption;
                                                 var  Longind:  LongInt)  :  Char

    Visibility:   default

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 (521  ) 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 (521  ).

    See also:    Getopt (521  )
                9.3.2        GetOpt

    Synopsis:    Get next short option.

Declaration:     function  GetOpt(ShortOpts:  String)  :  Char

    Visibility:   default

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 (521  )



                                                                                 521

_________________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'GETOPTS'_________________________________*
 *___
Listing:  ./optex/optex.pp
______________________________________________________________________________________________________________________________
program        t e s t o p t;


{   Program       t o  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 t o  t h i s  p r o g r a m 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--   a p p e n d--   c r e a t e c h i l d
    o p t e x - ab   - c  me   - d   you
    and    s o  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 ] o f  TOption     ;


 b e g i n
    w i t h  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  ;
    w i t h  t h e o p t s[ 2 ] do
      b e g i n
       name   :=  ' a p p e n d';
        h a s _a r g: = 0 ;
        f l a g:= n i l;
        v a l u e:=#0;
    end  ;
    w i t h  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  ;
    w i t h  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  ;
    w i t h  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  ;
    w i t h  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 ;



                                                                 522

_________________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'GETOPTS'_________________________________*
 *___
        f l a g:= n i l;
        v a l u e:=#0;
    end  ;
    w i t h  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'a b c :d : 0 1 2' , @ t h e o p t s[ 1 ] ,o p t i o n i n d e)x;
        c a s e c   o f
           ' 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 s[o 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 g>0   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  o p t  :   ' ,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___._______________________________________________________________________________________________________________________


                                                                 523


Chapter   10


Reference   for   unit   'go32'
10.1          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

     o  %CS:%EIP = 48 bit pointer specified in the original call to get_rm_callback (542  )

     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



                                                             524

            _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________
            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 (542  ), free_rm_callback (538  ), lock_code (551  ), lock_data (551  )
            10.2          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 (560  ) and
            it's linear address via transfer_buffer (560  ).  Another way is to allocate a completely new dos
            memory area via the global_dos_alloc (548  ) function for your use and supply its real mode
            address.


See also:    tb_size  (560  ),  transfer_buffer  (560  ),  global_dos_alloc  (548  ),  global_dos_free  (549  ),  realintr
            (553  )
            10.3          Software  interrupts


            Ordinarily, a handler installed with set_pm_interrupt (557  ) only services software interrupts
            that  are  executed  in  protected  mode;  real  mode  software  interrupts  can  be  redirected  by
            set_rm_interrupt (558  ).


See also:    set_rm_interrupt  (558  ),  get_rm_interrupt  (545  ),  set_pm_interrupt  (557  ),  get_pm_interrupt
            (542  ), lock_data (551  ), lock_code (551  ), enable (537  ), disable (535  ), outportb (552  )
            10.4          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.
                                                                             525

            _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________
            10.5          Disabling  interrupts


            The GO32 unit provides the two procedures disable() and enable() to disable and enable all
            interrupts.
            10.6          Creating  your  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.
            10.7          Protected   mode   interrupts   vs.    Real   mode   inter-

                          rupts


            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.
            10.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.
            10.9          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.
            10.10            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 (538  ), get_ds (539  ), get_ss (547  )
                                                                             526

            _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________
            10.11            I/O  port  access


            The I/O port access is done via the various inportb (550  ), outportb (552  ) 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 (552  ), inportb (550  )
            10.12            dos  memory  access


            Dos memory is accessed by the predefined dosmemselector selector;  the GO32 unit addi-
            tionally 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  (529  ),  dosmemput  (529  ),  dosmemmove  (529  ),  dosmemfillchar  (528  ),  dosmem-
            fillword (529  ), seg_move (556  ), seg_fillchar (555  ), seg_fillword (556  )
            10.13            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
            functions.  Luckily we asm programmers can still use the %gs selector for our own purposes,
            but for how long ?


See also:    get_cs  (538  ),  get_ds  (539  ),  get_ss  (547  ),  allocate_ldt_descriptors  (532  ),  free_ldt_descriptor
            (537  ), segment_to_descriptor (554  ), get_next_selector_increment_value (541  ), get_segment_base_address
            (546  ), set_segment_base_address (559  ), set_segment_limit (559  ), create_code_segment_alias_descriptor
            (535  )
            10.14            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
            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.
                                                                             527

_______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___
10.15            What  is  DPMI


The dos Protected Mode Interface helps you with various aspects of protected mode program-
ming.  These are roughly divided into descriptor handling, access to dos memory, manage-
ment of interrupts and exceptions, calls to real mode functions and other stuff.  Additionally
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.
10.16            Overview


This  document  describes  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.

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
10.17            Constants,  types  and  variables



10.17.1          Constants

auxcarryflag  =  $010


Check for auxiliary carry flag in trealregs (531  )


carryflag  =  $001


Check for carry flag in trealregs (531  )


directionflag  =  $400


Check for direction flag in trealregs (531  )


dosmemfillchar  :  procedure(seg:  Word;ofs:  Word;count:  LongInt;c:  Char)  =  @dpmi_dosmemfillchar


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.



                                                                 528

_______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___
dosmemfillword  :  procedure(seg:  Word;ofs:  Word;count:  LongInt;w:  Word)  =  @dpmi_dosmemfillword


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.


dosmemget  :  procedure(seg:  Word;ofs:  Word;var  data;count:  LongInt)  =  @dpmi_dosmemget


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.

For an example, see global_dos_alloc (548  ).


dosmemmove  :  procedure(sseg:  Word;sofs:  Word;dseg:  Word;dofs:  Word;count:  LongInt)  =  @dpmi_dosmemmove


Copies count bytes of data between two dos real mode memory locations.

Parameters:


sseg   source real mode segment.

sofs   source real mode offset.

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.


dosmemput  :  procedure(seg:  Word;ofs:  Word;var  data;count:  LongInt)  =  @dpmi_dosmemput


Copies heap data to dos real mode memory.

Parameters:


seg   destination real mode segment.



                                                                 529

_______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___
ofs  destination real mode offset.

data    source.

count     number of bytes to copy.


Notes:  No range checking is performed.

For an example, see global_dos_alloc (548  ).


interruptflag  =  $200


Check for interrupt flag in trealregs (531  )


overflowflag  =  $800


Check for overflow flag in trealregs (531  )


parityflag  =  $004


Check for parity flag in trealregs (531  )


rm_dpmi  =  4


get_run_mode (546  ) return value:  DPMI (e.g.  dos box or 386Max)


rm_raw  =  1


get_run_mode (546  ) return value:  raw (without HIMEM)


rm_unknown  =  0


get_run_mode (546  ) return value:  Unknown runmode


rm_vcpi  =  3


get_run_mode (546  ) return value:  VCPI (with HIMEM and EMM386)


rm_xms  =  2


get_run_mode (546  ) return value:  XMS (with HIMEM, without EMM386)


signflag  =  $080


Check for sign flag in trealregs (531  )


trapflag  =  $100


Check for trap flag in trealregs (531  )


zeroflag  =  $040


Check for zero flag in trealregs (531  )



                                                                 530

_______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___
10.17.2          Types

registers  =  trealregs


Alias for trealregs (531  )


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;
    reserved0  :  LongInt;
    reserved1  :  LongInt;
    reserved2  :  LongInt;
end



tmeminfo 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.


trealregs  =  record
end



The trealregs type contains the data structure to pass register values to a interrupt handler
or real mode callback.


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
10.17.3          Variables

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.


int31error  :  Word


This variable holds the result of a DPMI interrupt call.  Any nonzero value must be treated
as a critical failure.



                                                                 531

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18            Procedures  and  functions



                10.18.1          allocate__ldt__descriptors

    Synopsis:    Allocate a number of descriptors

Declaration:     function  allocate_ldt_descriptors(count:  Word)  :  Word

    Visibility:   default

Description:     Allocates a number of new descriptors.

                Parameters:


                count:\      specifies the number of requested unique descriptors.


                Return value:  The base selector.

 Remark:         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
                (541  ) function.

       Errors:   Check the int31error (531  ) variable.

    See also:    free_ldt_descriptor (537  ), get_next_selector_increment_value (541  ), segment_to_descriptor (554  ),
                create_code_segment_alias_descriptor (535  ), set_segment_limit (559  ), set_segment_base_address
                (559  )


                Listing:  ./go32ex/seldes.pp
                ___________________________________________________________________________________________________________________*
 *___________
                { $mode      d e l p h i}
                 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 ;


                 t y p e
                               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 e- 1 ] o f  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
                         g o t o x y( 1 ,  1 ) ;  c l r e o l;  w r i t e(s ) ;  r e a d k e y;
                end   ;

                                                                                 532

_______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___
 p r o c e d u r es e l i n f o(s e l  :  Word    ) ;
 b e g i n
         g o t o x y( 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 rb 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 s(ss e l) ,  8 ) ) ;
         c l r e o l;  w r i t e( ' D e s c r i p t o rl 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 nm a k e c h a r(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  )  o r  (  c o l o r s h l  8 ) ;
end   ;


 b e g i n
         s e g _m o v e( d o s m e m s e l e c t o,r l i n B 8 0 0 0, g e t _d s ,  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,r l i n B 8 0 0 0, s c r e e n s i z ed i v  2 ,
              m a k e c h a r( '  ' ,  B l a c k o r  ( 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' '  t o  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 r(s1 ) ;
         s e t _s e g m e n t _b a s e _a d d r e s(st e 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 i t(t e x t _s e l,  s c r e e n s i z e-  1  -    b y t e s p e r c e l l*
              maxx     *  3 ) ;
          s e l i n f(ot 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 t(t e x t _s e l) + 1 ) d i v  2 ,
              m a k e c h a r( '  ' ,  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 dby    t h e' +
               '  d e s c r i p t o rc 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 dmemory     ' ) ;
         s e t _s e g m e n t _b a s e _a d d r e s(st e x t _s e l,
               g e t _s e g m e n t _b a s e _a d d r e s(st e x 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 i t(t e x t _s e l,
               g e t _s e g m e n t _l i m i(tt e 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(ot 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 dby   one    l i n e  b u t  ' +
               't h e  l i m i t  d e c r e a s e dby   2   l 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 et o  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 t(t e x t _s e l) + 1 ) d i v  2 ,
              m a k e c h a r( # 1 7 6 , L i g h t M a g e n t ao r 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    c o p y 1 0   l i n e s o f  d a t a  f r o m  ' +
               't h e  p r e v i o u s l ys a v e d  s c r e e n') ;
         s e g _m o v e( g e t _d s ,  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 rand    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 ep r o g r a m may    g i v e  you    some     h i n t s on    '+
                                                                 533

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                               '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 o(rt e x t _s e l) ;
                         s e g _m o v e( g e t _d s ,  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,r
                               l i n B 8 0 0 0, s c r e e n s i z e) ;
                         g o t o x y( t e x t _o l d x,  t e x t _o l d y) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.2          allocate__memory__block

    Synopsis:    Allocate a block of linear memory

Declaration:     function  allocate_memory_block(size:  LongInt)  :  LongInt

    Visibility:   default

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.

 Remark:         warning  According to my DPMI docs this function is 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 (531  ) variable.

    See also:    free_memory_block (538  )
                10.18.3          copyfromdos

    Synopsis:    Copy data from DOS to to heap

Declaration:     procedure  copyfromdos(var  addr;len:  LongInt)

    Visibility:   default

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 (531  ) variable.

    See also:    tb_size (560  ), transfer_buffer (560  ), copytodos (535  )



                                                                                 534

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.4          copytodos

    Synopsis:    Copy data from heap to DOS memory

Declaration:     procedure  copytodos(var  addr;len:  LongInt)

    Visibility:   default

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 (531  ) variable.

    See also:    tb_size (560  ), transfer_buffer (560  ), copyfromdos (534  )
                10.18.5          create__code__segment__alias__descriptor

    Synopsis:    Create new descriptor from existing descriptor

Declaration:     function  create_code_segment_alias_descriptor(seg:  Word)  :  Word

    Visibility:   default

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 (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), set_segment_limit (559  ), set_segment_base_address (559  )
                10.18.6          disable

    Synopsis:    Disable hardware interrupts

Declaration:     procedure  disable

    Visibility:   default

Description:     Disables all hardware interrupts by execution a CLI instruction.

       Errors:   None.

    See also:    enable (537  )

                                                                                 535

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.7          dpmi__dosmemfillchar

    Synopsis:    Fill DOS memory with a character

Declaration:     procedure  dpmi_dosmemfillchar(seg:  Word;ofs:  Word;count:  LongInt;
                                                                c:  Char)

    Visibility:   default

Description:     dpmi_dosmemfillchar fills the DOS memory reagion indicated by seg,ofs with count char-
                acters c.

    See also:    dpmi_dosmemput (537  ), dpmi_dosmemget (536  ), dpmi_dosmemmove (536  ), dpmi_dosmemfillword
                (536  )
                10.18.8          dpmi__dosmemfillword

    Synopsis:    Fill DOS memory with a word value

Declaration:     procedure  dpmi_dosmemfillword(seg:  Word;ofs:  Word;count:  LongInt;
                                                                w:  Word)

    Visibility:   default

Description:     dpmi_dosmemfillword fills the DOS memory reagion indicated by seg,ofs with count words
                W.

    See also:    dpmi_dosmemput (537  ), dpmi_dosmemget (536  ), dpmi_dosmemfillchar (536  ), dpmi_dosmemmove
                (536  )
                10.18.9          dpmi__dosmemget

    Synopsis:    Move data from DOS memory to DPMI memory

Declaration:     procedure  dpmi_dosmemget(seg:  Word;ofs:  Word;var  data;count:  LongInt)

    Visibility:   default

Description:     dpmi_dosmemput moves count bytes of data from the DOS memory location indicated by
                seg and ofs to DPMI memory indicated by data.

    See also:    dpmi_dosmemput (537  ), dpmi_dosmemmove (536  ), dpmi_dosmemfillchar (536  ), dpmi_dosmemfillword
                (536  )
                10.18.10           dpmi__dosmemmove

    Synopsis:    Move DOS memory

Declaration:     procedure  dpmi_dosmemmove(sseg:  Word;sofs:  Word;dseg:  Word;dofs:  Word;
                                                         count:  LongInt)

    Visibility:   default

Description:     dpmi_dosmemmove moves count bytes from DOS memory sseg,sofs to dseg,dofs.

    See also:    dpmi_dosmemput (537  ), dpmi_dosmemget (536  ), dpmi_dosmemfillchar (536  ), dpmi_dosmemfillword
                (536  )

                                                                                 536

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.11           dpmi__dosmemput

    Synopsis:    Move data from DPMI memory to DOS memory.

Declaration:     procedure  dpmi_dosmemput(seg:  Word;ofs:  Word;var  data;count:  LongInt)

    Visibility:   default

Description:     dpmi_dosmemput moves count bytes of data from data to the DOS memory location indi-
                cated by seg and ofs.

    See also:    dpmi_dosmemget (536  ), dpmi_dosmemmove (536  ), dpmi_dosmemfillchar (536  ), dpmi_dosmemfillword
                (536  )
                10.18.12           enable

    Synopsis:    Enable hardware interrupts

Declaration:     procedure  enable

    Visibility:   default

Description:     Enables all hardware interrupts by executing a STI instruction.

       Errors:   None.

    See also:    disable (535  )
                10.18.13           free__ldt__descriptor

    Synopsis:    Free a descriptor

Declaration:     function  free_ldt_descriptor(d:  Word)  :  Boolean

    Visibility:   default

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 (532  ) must be freed individually with this function,  even if it
                was previously allocated as a part of a contiguous array of descriptors.

                For an example, see allocate_ldt_descriptors (532  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), get_next_selector_increment_value (541  )

                                                                                 537

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.14           free__memory__block

    Synopsis:    Free allocated memory block

Declaration:     function  free_memory_block(blockhandle:  LongInt)  :  Boolean

    Visibility:   default

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  (534  )  .   This  function  doesn't  free  any  descriptors
                mapped to this block, it's the application's responsibility.

       Errors:   Check int31error (531  ) variable.

    See also:    allocate_memory_block (534  )
                10.18.15           free__rm__callback

    Synopsis:    Release real mode callback.

Declaration:     function  free_rm_callback(var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     Releases a real mode callback address that was previously allocated with the get_rm_callback
                (542  ) function.

                Parameters:


                intaddr     real mode address buffer returned by get_rm_callback (542  ) .


                Return values:  True if successful, False if not

                For an example, see get_rm_callback (542  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    set_rm_interrupt (558  ), get_rm_callback (542  )
                10.18.16           get__cs

    Synopsis:    Get CS selector

Declaration:     function  get_cs  :  Word

    Visibility:   default

Description:     Returns the cs selector.

                Return value:  The content of the cs segment register.

                For an example, see set_pm_interrupt (557  ).

       Errors:   None.

    See also:    get_ds (539  ), get_ss (547  )
                                                                                 538

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.17           get__descriptor__access__right

    Synopsis:    Get descriptor's access rights

Declaration:     function  get_descriptor_access_right(d:  Word)  :  LongInt

    Visibility:   default

Description:     Gets the access rights of a descriptor.

                Parameters:


                d selector to descriptor.


                Return value:  Access rights bit field.

       Errors:   Check the int31error (531  ) variable.

    See also:    set_descriptor_access_right (557  )
                10.18.18           get__ds

    Synopsis:    Get DS Selector

Declaration:     function  get_ds  :  Word

    Visibility:   default

Description:     Returns the ds selector.

                Return values:  The content of the ds segment register.

       Errors:   None.

    See also:    get_cs (538  ), get_ss (547  )
                10.18.19           get__exception__handler

    Synopsis:    Return current exception handler

Declaration:     function  get_exception_handler(e:  Byte;var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     get_exception_handler returns the exception handler for exception E in intaddr.  It re-
                turns True if the call was successful, False if not.

    See also:    set_exception_handler (557  ), get_pm_exception_handler (542  )
                10.18.20           get__linear__addr

    Synopsis:    Convert physical to linear address

Declaration:     function  get_linear_addr(phys_addr:  LongInt;size:  LongInt)  :  LongInt

    Visibility:   default

Description:     Converts a physical address into a linear address.

                Parameters:


                phys__addr      physical address of device.



                                                                                 539

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                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 (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), set_segment_limit (559  ), set_segment_base_address (559  )
                10.18.21           get__meminfo

    Synopsis:    Return information on the available memory

Declaration:     function  get_meminfo(var  meminfo:  tmeminfo)  :  Boolean

    Visibility:   default

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.

 Remark:          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 (541  ) function.

       Errors:   Check the int31error (531  ) variable.

    See also:    get_page_size (541  )


                Listing:  ./go32ex/meminfo.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 u s e s
                              go32    ;


                 v a r
                              meminfo        :  t m e m i n f o;


                 b e g i n
                               g e t _m e m i n f o(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 gDPMI     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 b e g i n
                                            w i t h  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 v  1 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 eu 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 ep 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;



                                                                                 540

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                                                           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 e*g e t _p a g e _s i z *
 *e d i v  1 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 c*eg e t _p a g *
 *e _s i z e d 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 l e*g*
 * e t _p a g e _s i z e d i v  1 0 2 4 ,
                                                                                       '  k b y t e s') ;
                                            end   ;
                              end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.22           get__next__selector__increment__value

    Synopsis:    Return selector increment value

Declaration:     function  get_next_selector_increment_value  :  Word

    Visibility:   default

Description:     Returns  the  selector  increment  value  when  allocating  multiple  subsequent  descriptors  via
                allocate_ldt_descriptors (532  ).

                Return value:  Selector increment value.

 Remark:         Notes:  Because allocate_ldt_descriptors (532  ) 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 (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), free_ldt_descriptor (537  )
                10.18.23           get__page__size

    Synopsis:    Return the page size

Declaration:     function  get_page_size  :  LongInt

    Visibility:   default

Description:     Returns the size of a single memory page.

                Return value:  Size of a single page in bytes.

 Remark:         The returned size is typically 4096 bytes.

                For an example, see get_meminfo (540  ).



                                                                                 541

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
       Errors:   Check the int31error (531  ) variable.

    See also:    get_meminfo (540  )
                10.18.24           get__pm__exception__handler

    Synopsis:    Get protected mode exception handler

Declaration:     function  get_pm_exception_handler(e:  Byte;var  intaddr:  tseginfo)
                                                                        :  Boolean

    Visibility:   default

Description:     get_pm_exception_handler returns the protected mode exception handler for exception E
                in intaddr.  It returns True if the call was successful, False if not.

    See also:    get_exception_handler (539  ), set_pm_exception_handler (557  )
                10.18.25           get__pm__interrupt

    Synopsis:    Return protected mode interrupt handler

Declaration:     function  get_pm_interrupt(vector:  Byte;var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

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.

 Remark:         The returned address is a protected mode selector:offset address.

                For an example, see set_pm_interrupt (557  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    set_pm_interrupt (557  ), set_rm_interrupt (558  ), get_rm_interrupt (545  )
                10.18.26           get__rm__callback

    Synopsis:    Return real mode callback

Declaration:     function  get_rm_callback(pm_func:  pointer;const  reg:  trealregs;
                                                        var  rmcb:  tseginfo)  :  Boolean

    Visibility:   default

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.
                                                                                 542

               _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'______________*
 *__________________
               rmcb    buffer to real mode address of callback function.


               Return values:  True if successful, otherwise False.

Remark:        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.

      Errors:   Check the int31error (531  ) variable.

   See also:    free_rm_callback (538  )


               Listing:  ./go32ex/callback.pp
               ____________________________________________________________________________________________________________________*
 *__________
               { $ASMMODE        ATT  }
               { $MODE     FPC   }


                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
                              m o u s e _r e g s      :   t r e a l r e g;s  e x t e r n a lname     ' _ __v 2 p r t 0 _r m c b _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
                             m o u s e _n u m b u t t o n s:   l o n g i n t;


                              m o u s e _a c t i o n:   word   ;
                             mouse _x     ,  m o u s e _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;


                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    %  d s
                     p u s h l%  e a x
                    movw    %  e s ,  % a x
                    movw    %  ax  ,  % d s


                     cmpl    $1  ,  USERPROC_INSTALLED
                     j n e  . L N o C a l l b a c k
                     p u s h a l
                    movw     DOSmemSELECTOR           ,  % a x
                    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 a x
                     popw   %  d s



                                                                                543

_______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___


      p u s h l%  e a x
      movl    (%  e s i) ,  % e a x
      movl   %  eax  ,  %  e s:  4 2 ( % e d i)
      addw    $4  ,  % e s :46(%    e d i)
      p o p l%  e a x
      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      : =   m o u s e _r e g s.bx ;
              m o u s e _x  : =  ( m o u s e _r e g s. c x  s h r  3 )  +  1 ;
              m o u s e _y  : =  ( m o u s e _r e g s.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. e a x  : =  $0  ;  r e a l i n t r(m o u s e i n t, r ) ;
               i f  ( r. e a x <>    $FFFF    )  then     b e g i n
                            W r i t e l n( 'No   M i c r o s o f t c o m p a t i b l emouse     f o u n d' ) ;
                            W r i t e l n( 'A   M i c r o s o f tc o m p a t i b l emouse      d r i v e r i s  n e c e s s a r y '*
 * ,
                                           't o  r u n   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     m o u s e _n u m b u t t o n s: =  2
               e l s e m o u s e _n u m b u t t o n s: =  r .bx  ;
               W r i t e l n(m o u s e _n u m b u t t o n,s '  b u t t o n  M i c r o s o f tc o m p a t i b l emouse      ' ,
                             '  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 e(u 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 a(mouse _x    ,   s i z e o f(m o u s e _x) ) ;
               l o c k _d a t a(mouse _y    ,   s i z e o f(m o u s e _y) ) ;
               l o c k _d a t a(mouse _b    ,   s i z e o f(mouse _b    ) ) ;
               l o c k _d a t a(m 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 a(u 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) ;
               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 a(m o u s e _r e g s,  s i z e o f(m o u s e _r e g s) ) ;
               l o c k _d a t a(m 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 e,r m o u s e _r e g s,  m o u s e _s e g i n f)o;
               r. e a x  : =  $ 0 c ;  r .e c x  : =   $ 7 f;
               r. e d x  : =  l o n g i n t(m o u s e _s e g i n f o.o f f s e t) ;
               r. e s  : =   m o u s e _s e g i n f.os e g m e n t;
               r e a l i n t(rm o u s e i n t,  r ) ;
                                                                 544

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                               r. e a x  : =  $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 er e m o v e _m o u s e;
                 v a r
                               r  :   t r e a l r e g;s
                 b e g i n
                               r. e a x  : =  $02   ;  r e a l i n t r(m o u s e i n t, r ) ;
                               r. e a x  : =  $ 0 c ;  r .e c x  : =  0 ;   r .e d x  : =  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 c(km o 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
                                             u n l o c k _c o d e(u 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 a(mouse _x    ,  s i z e o f(m o u s e _x ) ) ;
                               u n l o c k _d a t a(mouse _y    ,  s i z e o f(m o u s e _y ) ) ;
                               u n l o c k _d a t a(mouse _b    ,  s i z e o f(mouse _b     ) ) ;
                               u n l o c k _d a t a(m 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,c  s 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 a(u 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) ;


                               u n l o c k _d a t a(m o u s e _r e g s, s i z e o f( m o u s e _r e g s) ) ;
                               u n l o c k _d a t a(m 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    k e y  t o  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
                                            g o t o x y( 1 ,  wherey     ) ;
                                             w r i t e('MouseX       :   ' ,  m o u s e _x: 2 ,  '  MouseY       :  ' ,  m o u s e *
 *_y: 2 ,
                                                           '  B u t t o n s :   ' , mouse _b     : 2 ) ;
                              end   ;
                              r e m o v e _m o u s e;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.27           get__rm__interrupt

    Synopsis:    Get real mode interrupt vector

Declaration:     function  get_rm_interrupt(vector:  Byte;var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     Returns the contents of the current machine's real mode interrupt vector for the specified
                interrupt.

                Parameters:

                                                                                 545

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                vector   interrupt vector number.

                intaddr    buffer to store real mode segment:offset address.


                Return values:  True if successful, False otherwise.

 Remark:         The returned address is a real mode segment address, which isn't valid in protected mode.

       Errors:   Check the int31error (531  ) variable.

    See also:    set_rm_interrupt (558  ), set_pm_interrupt (557  ), get_pm_interrupt (542  )
                10.18.28           get__run__mode

    Synopsis:    Return current run mode

Declaration:     function  get_run_mode  :  Word

    Visibility:   default

Description:     Returns the current mode your application runs with.

                Return values:  One of the constants used by this function.

       Errors:   None.

    See also:    get_run_mode (546  )


                Listing:  ./go32ex/getrunmd.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 u s e s
                              go32    ;


                 b e g i n
                              c a s e  ( g e t _r u n _m o d e)  o f
                                            rm _unknown         :
                                                          W r i t e l n( 'Unknown       e n v i r o n m e n tf 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 tHIMEM    )  ') ;
                                            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 gHIMEM     .SYS  *
 *  o n l y ') ;
                                             r m _v c p i       :
                                                          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   DPM*
 *I     h o s t  l i k e  ',
                                                                         'a  windows       DOS    box    o r  CWSDPMI      ' ) ;
                              end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.29           get__segment__base__address

    Synopsis:    Return base address from descriptor table

Declaration:     function  get_segment_base_address(d:  Word)  :  LongInt

    Visibility:   default

                                                                                 546

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
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.

                For an example, see allocate_ldt_descriptors (532  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), set_segment_base_address (559  ), allocate_ldt_descriptors (532  ),
                set_segment_limit (559  ), get_segment_limit (547  )
                10.18.30           get__segment__limit

    Synopsis:    Return segment limite from descriptor

Declaration:     function  get_segment_limit(d:  Word)  :  LongInt

    Visibility:   default

Description:     Returns a descriptors segment limit.

                Parameters:


                d selector.


                Return value:  Limit of the descriptor in bytes.

       Errors:   Returns zero if descriptor is invalid.

    See also:    allocate_ldt_descriptors (532  ), set_segment_limit (559  ), set_segment_base_address (559  ), get_segment_base_ad*
 *dress
                (546  )
                10.18.31           get__ss

    Synopsis:    Return SS selector

Declaration:     function  get_ss  :  Word

    Visibility:   default

Description:     Returns the ss selector.

                Return values:  The content of the ss segment register.

       Errors:   None.

    See also:    get_ds (539  ), get_cs (538  )



                                                                                 547

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.32           global__dos__alloc

    Synopsis:    Allocate DOS real mode memory

Declaration:     function  global_dos_alloc(bytes:  LongInt)  :  LongInt

    Visibility:   default

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 (549  ) call.

       Errors:   Check the int31error (531  ) variable.

    See also:    global_dos_free (549  )


                Listing:  ./go32ex/buffer.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 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 s e g m e n t  :  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 c(s i z e) ;
                               s e l e c t o r: =  word   ( r e s ) ;
                              s e g m e n t : =   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
                               g l o b a l _d o s _f r e e(s e l e c t o r) ;
                end   ;


                 t y p e
                              V B E I n f o B u f=   packed      r e c o r d
                                             S i g n a t u r e:  a r r a y[ 0 . . 3 ] o f   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 ]o f  b y t e;
                              end   ;


                 v a r
                               s e l e c t o r,
                              s e g m e n t  :  Word   ;
                                                                                 548

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                               r  :   t r e a l r e g;s
                               i n f o b u f :  V B E I n f o B u f;


                 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(V B E I n f o B u f) ,  0 ) ;
                               d o s a l l o(cs e l e c t o r,  segment     ,  s i z e o f(V B E I n f o B u f) ) ;
                               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 gr 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. a x  : =  $ 4 f 0 0;   r .e s  : =   s e g m e n t;
                               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. a x <>    $ 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 nn o t  a v a i l a b l e,  f u n c t i*
 * o nc 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 e[ 2 ]  =  '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 e t e c t e d') ;
                              end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.33           global__dos__free

    Synopsis:    Free DOS memory block

Declaration:     function  global_dos_free(selector:  Word)  :  Boolean

    Visibility:   default

Description:     Frees a previously allocated dos memory block.

                Parameters:


                selector    selector to the dos memory block.


                Return value:  True if successful, False otherwise.

 Remark:         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
                (548  ).

                For an example, see global_dos_alloc (548  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    global_dos_alloc (548  )
                                                                                 549

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.34           inportb

    Synopsis:    Read byte from I/O port

Declaration:     function  inportb(port:  Word)  :  Byte

    Visibility:   default

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 (552  ), inportw (550  ), inportl (550  )
                10.18.35           inportl

    Synopsis:    Read longint from I/O port

Declaration:     function  inportl(port:  Word)  :  LongInt

    Visibility:   default

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 (552  ), inportb (550  ), inportw (550  )
                10.18.36           inportw

    Synopsis:    Read word from I/O port

Declaration:     function  inportw(port:  Word)  :  Word

    Visibility:   default

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 (553  ), inportb (550  ), inportl (550  )



                                                                                 550

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.37           lock__code

    Synopsis:    Lock code memory range

Declaration:     function  lock_code(functionaddr:  pointer;size:  LongInt)  :  Boolean

    Visibility:   default

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.

                For an example, see get_rm_callback (542  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    lock_linear_region (551  ), lock_data (551  ), unlock_linear_region (561  ), unlock_data (561  ), un-
                lock_code (561  )
                10.18.38           lock__data

    Synopsis:    Lock data memory range

Declaration:     function  lock_data(var  data;size:  LongInt)  :  Boolean

    Visibility:   default

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.

                For an example, see get_rm_callback (542  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    lock_linear_region (551  ), lock_code (551  ), unlock_linear_region (561  ), unlock_data (561  ), un-
                lock_code (561  )
                10.18.39           lock__linear__region

    Synopsis:    Lock linear memory region

Declaration:     function  lock_linear_region(linearaddr:  LongInt;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Locks a memory region to prevent swapping of it.

                Parameters:


                linearaddr      the linear address of the memory are to be locked.
                                                                                 551

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                size size in bytes to be locked.


                Return value:  True if successful, False otherwise.

       Errors:   Check the int31error (531  ) variable.

    See also:    lock_data (551  ), lock_code (551  ), unlock_linear_region (561  ), unlock_data (561  ), unlock_code
                (561  )
                10.18.40           map__device__in__memory__block

    Synopsis:    Map a device into program's memory space

Declaration:     function  map_device_in_memory_block(handle:  LongInt;offset:  LongInt;
                                                                          pagecount:  LongInt;device:  LongInt)
                                                                            :  Boolean

    Visibility:   default

Description:     map_device_in_memory_block allows to map a device in memory.  This function is a direct
                call of the extender.  For more information about it's arguments, see the extender documen-
                tation.
                10.18.41           outportb

    Synopsis:    Write byte to I/O port

Declaration:     procedure  outportb(port:  Word;data:  Byte)

    Visibility:   default

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 (550  ), outportl (553  ), outportw (553  )


                Listing:  ./go32ex/outport.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 u s e s
                               c r t,
                              go32    ;


                 b e g i n
                               o u t p o r t(b$61   ,  $ f f) ;
                               d e l a y( 5 0 ) ;
                               o u t p o r t(b$61   ,  $0  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________
                                                                                 552

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.42           outportl

    Synopsis:    Write longint to I/O port

Declaration:     procedure  outportl(port:  Word;data:  LongInt)

    Visibility:   default

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.

                For an example, see outportb (552  ).

       Errors:   None.

    See also:    inportl (550  ), outportw (553  ), outportb (552  )
                10.18.43           outportw

    Synopsis:    Write word to I/O port

Declaration:     procedure  outportw(port:  Word;data:  Word)

    Visibility:   default

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.

                For an example, see outportb (552  ).

       Errors:   None.

    See also:    inportw (550  ), outportl (553  ), outportb (552  )
                10.18.44           realintr

    Synopsis:    Simulate interrupt

Declaration:     function  realintr(intnr:  Word;var  regs:  trealregs)  :  Boolean

    Visibility:   default

Description:     Simulates an interrupt in real mode.

                Parameters:


                intnr   interrupt number to issue in real mode.

                regs   registers data structure.

                                                                                 553

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                Return values:  The supplied registers data structure contains the values that were returned
                by the real mode interrupt.  True if successful, False if not.

 Remark:         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 (531  ) variable.


                Listing:  ./go32ex/flags.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 u s e s
                              go32    ;


                 v a r
                               r  :   t r e a l r e g;s


                 b e g i n
                               r. a x  : =  $5300    ;
                               r. bx   : =  0 ;
                               r e a l i n t(r$15   ,  r ) ;
                               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    n o t  p r e s e n t') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.45           request__linear__region

    Synopsis:    Request linear address region.

Declaration:     function  request_linear_region(linearaddr:  LongInt;size:  LongInt;
                                                                  var  blockhandle:  LongInt)  :  Boolean

    Visibility:   default

Description:     request_linear_region requests a linear range of addresses of size Size, starting at linearaddr.
                If successful, True is returned, and a handle to the address region is returned in blockhandle.

       Errors:   On error, False is returned.
                10.18.46           segment__to__descriptor

    Synopsis:    Map segment address to descriptor

Declaration:     function  segment_to_descriptor(seg:  Word)  :  Word

    Visibility:   default

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.
                                                                                 554

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                Return values:  Descriptor to real mode segment address.

 Remark:         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 (532  ) and change the
                base address as necessary.

                For an example, see seg_fillchar (555  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), free_ldt_descriptor (537  ), set_segment_base_address (559  )
                10.18.47           seg__fillchar

    Synopsis:    Fill segment with byte value

Declaration:     procedure  seg_fillchar(seg:  Word;ofs:  LongInt;count:  LongInt;c:  Char)

    Visibility:   default

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 (556  ), seg_fillword (556  ), dosmemfillchar (528  ), dosmemfillword (529  ), dosmemget
                (529  ), dosmemput (529  ), dosmemmove (529  )


                Listing:  ./go32ex/vgasel.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 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. e a x  : =  $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(r$A000   ) ;
                               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;
                               r. e a x  : =  $3  ;  r e a l i n t r($10  ,   r ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                 555

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.48           seg__fillword

    Synopsis:    Fill segment with word value

Declaration:     procedure  seg_fillword(seg:  Word;ofs:  LongInt;count:  LongInt;w:  Word)

    Visibility:   default

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.

                For an example, see allocate_ldt_descriptors (532  ).

       Errors:   None.

    See also:    seg_move (556  ), seg_fillchar (555  ), dosmemfillchar (528  ), dosmemfillword (529  ), dosmemget
                (529  ), dosmemput (529  ), dosmemmove (529  )
                10.18.49           seg__move

    Synopsis:    Move data between 2 locations

Declaration:     procedure  seg_move(sseg:  Word;source:  LongInt;dseg:  Word;dest:  LongInt;
                                              count:  LongInt)

    Visibility:   default

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.

 Remark:         Overlapping is only checked if the source selector is equal to the destination selector.  No
                range check is done.

                For an example, see allocate_ldt_descriptors (532  ).

       Errors:   None.

    See also:    seg_fillchar (555  ), seg_fillword (556  ), dosmemfillchar (528  ), dosmemfillword (529  ), dosmemget
                (529  ), dosmemput (529  ), dosmemmove (529  )


                                                                                 556

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.50           set__descriptor__access__right

    Synopsis:    Set access rights to memory descriptor

Declaration:     function  set_descriptor_access_right(d:  Word;w:  Word)  :  LongInt

    Visibility:   default

Description:     set_descriptor_access_right sets the access rights for descriptor d to w
                10.18.51           set__exception__handler

    Synopsis:    Set exception handler

Declaration:     function  set_exception_handler(e:  Byte;const  intaddr:  tseginfo)
                                                                   :  Boolean

    Visibility:   default

Description:     set_exception_handler sets the exception handler for exception E to intaddr.  It returns
                True if the call was successful, False if not.

    See also:    get_exception_handler (539  ), set_pm_exception_handler (557  )
                10.18.52           set__pm__exception__handler

    Synopsis:    Set protected mode exception handler

Declaration:     function  set_pm_exception_handler(e:  Byte;const  intaddr:  tseginfo)
                                                                        :  Boolean

    Visibility:   default

Description:     set_pm_exception_handler sets the protected mode exception handler for exception E to
                intaddr.  It returns True if the call was successful, False if not.

    See also:    set_exception_handler (557  ), get_pm_exception_handler (542  )
                10.18.53           set__pm__interrupt

    Synopsis:    Set protected mode interrupt handler

Declaration:     function  set_pm_interrupt(vector:  Byte;const  intaddr:  tseginfo)
                                                           :  Boolean

    Visibility:   default

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.

 Remark:         The address supplied must be a valid selector:offset protected mode address.

       Errors:   Check the int31error (531  ) variable.
                                                                                 557

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
    See also:    get_pm_interrupt (542  ), set_rm_interrupt (558  ), get_rm_interrupt (545  )


                Listing:  ./go32ex/intpm.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 u s e s
                               c r t,
                              go32    ;


                 c o n s t
                               i n t 1 c=   $ 1 c ;


                 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;


                               i n t 1 c _d s :  Word    ;  e x t e r n a l name     ' __ _v 2 p r t 0 _d s _a l i a s' ;


                 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    %  d s
                      pushw    %  a x
                     movw    %  c s : i n t 1 c _d s,  % a x
                     movw    %  ax  ,  % d s
                      i n c l  i n t 1 c _c o u n t e r
                      popw   %  a x
                      popw   %  d s
                      s t i
                      i r e t
                end   ;


                 v a r  i  :   L o n g i n t;


                 b e g i n
                         n e w i n t 1 c.o f f s e t : =   @ i n t 1 c _h a n d l e;r
                         n e w i n t 1 c.s e g m e n t : =  g e t _c s ;
                         g e t _p m _i n t e r r u p t(i n t 1 c,  o l d i n t 1 c) ;
                         W r i t e l n( '--   P r e s s  any    k e y  t o  e x i t--   ' ) ;
                         s e t _p m _i n t e r r u p t(i n 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
                                    g o t o x y( 1 , wherey     ) ;
                                    w r i t e( 'Number      o f   i n t e r r u p t so 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 p t(i n t 1 c,  o l d i n t 1 c) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                10.18.54           set__rm__interrupt

    Synopsis:    Set real mode interrupt handler

Declaration:     function  set_rm_interrupt(vector:  Byte;const  intaddr:  tseginfo)
                                                           :  Boolean

    Visibility:   default

                                                                                 558

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
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.

 Remark:         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 (542  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    get_rm_interrupt (545  ), set_pm_interrupt (557  ), get_pm_interrupt (542  ), get_rm_callback (542  )
                10.18.55           set__segment__base__address

    Synopsis:    Set descriptor's base address

Declaration:     function  set_segment_base_address(d:  Word;s:  LongInt)  :  Boolean

    Visibility:   default

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 (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), get_segment_base_address (546  ), allocate_ldt_descriptors (532  ),
                set_segment_limit (559  ), get_segment_base_address (546  ), get_segment_limit (547  )
                10.18.56           set__segment__limit

    Synopsis:    Set descriptor limit

Declaration:     function  set_segment_limit(d:  Word;s:  LongInt)  :  Boolean

    Visibility:   default

Description:     Sets the limit of a descriptor.

                Parameters:

                d selector.

                s new limit of the descriptor.

                Return values:  Returns True if successful, else False.

 Remark:         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.

                For an example, see allocate_ldt_descriptors (532  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    allocate_ldt_descriptors (532  ), set_segment_base_address (559  ), get_segment_limit (547  ), set_segment_limit
                (559  )



                                                                                 559

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.57           tb__offset

    Synopsis:    Return DOS transfer buffer offset

Declaration:     function  tb_offset  :  LongInt

    Visibility:   default

Description:     tb_offset returns the DOS transfer buffer segment.

    See also:    transfer_buffer (560  ), tb_segment (560  ), tb_size (560  )
                10.18.58           tb__segment

    Synopsis:    Return DOS transfer buffer segment

Declaration:     function  tb_segment  :  LongInt

    Visibility:   default

Description:     tb_segment returns the DOS transfer buffer segment.

    See also:    transfer_buffer (560  ), tb_offset (560  ), tb_size (560  )
                10.18.59           tb__size

    Synopsis:    Return DOS transfer memory buffer size

Declaration:     function  tb_size  :  LongInt

    Visibility:   default

Description:     Returns the size of the pre-allocated dos memory buffer.

                Return values:  The size of the pre-allocated dos memory buffer.  This block always seems to
                be 16k in size, but don't rely on this.

       Errors:   None.

    See also:    transfer_buffer (560  ), copyfromdos (534  ), copytodos (535  )
                10.18.60           transfer__buffer

    Synopsis:    Return offset of DOS transfer buffer

Declaration:     function  transfer_buffer  :  LongInt

    Visibility:   default

Description:     transfer_buffer returns the offset of the transfer buffer.

       Errors:   None.

    See also:    tb_size (560  )

                                                                                 560

                _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________
                10.18.61           unlock__code

    Synopsis:    Unlock code segment

Declaration:     function  unlock_code(functionaddr:  pointer;size:  LongInt)  :  Boolean

    Visibility:   default

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.

                For an example, see get_rm_callback (542  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    unlock_linear_region (561  ), unlock_data (561  ), lock_linear_region (551  ), lock_data (551  ), lock_code
                (551  )
                10.18.62           unlock__data

    Synopsis:    Unlock data segment

Declaration:     function  unlock_data(var  data;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Unlocks a memory range which resides in the data segment selector.

                Parameters:


                data   address of memory to be unlocked.

                size  size bytes to be unlocked.


                Return values:  True if successful, False otherwise.

                For an example, see get_rm_callback (542  ).

       Errors:   Check the int31error (531  ) variable.

    See also:    unlock_linear_region  (561  ),  unlock_code  (561  ),  lock_linear_region  (551  ),  lock_data  (551  ),
                lock_code (551  )
                10.18.63           unlock__linear__region

    Synopsis:    Unlock linear memory region

Declaration:     function  unlock_linear_region(linearaddr:  LongInt;size:  LongInt)
                                                                  :  Boolean

    Visibility:   default

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.



                                                                                 561

            _______________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________
            size size bytes to be unlocked.


            Return values:  True if successful, False otherwise.

   Errors:   Check the int31error (531  ) variable.

See also:    unlock_data  (561  ),  unlock_code  (561  ),  lock_linear_region  (551  ),  lock_data  (551  ),  lock_code
            (551  )

                                                                             562


Chapter   11


Reference   for   unit   'gpm'
11.1          Used  units
                                      Table 11.1:  Used units by unit 'gpm'


                                                  __Name____________Page_____
                                                    baseUnix          563



11.2          Overview


The GPM unit implements an interface to libgpm, 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.
11.3          Constants,  types  and  variables



11.3.1         Constants

GPM_BOT  =  2


Bottom of area.


GPM_B_LEFT  =  4


Left mouse button identifier.


GPM_B_MIDDLE  =  2


Middle mouse button identifier.


GPM_B_RIGHT  =  1



                                                             563

_______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___
Right mouse button identifier.


GPM_DOUBLE  =  32


Mouse double click event.


GPM_DOWN  =  4


Mouse button down event.


GPM_DRAG  =  2


Mouse drag event.


GPM_ENTER  =  512


Enter area event.


GPM_HARD  =  256


?


GPM_LEAVE  =  1024


Leave area event.


GPM_LFT  =  4


Left side of area.


GPM_MAGIC  =  $47706D4C


Constant identifying GPM in gpm_Open (571  ).


GPM_MFLAG  =  128


Motion flag.


GPM_MOVE  =  1


Mouse move event.


GPM_NODE_CTL  =  GPM_NODE_DEV


Control socket


GPM_NODE_DEV  =  '/dev/gpmctl'


Device socket filename


GPM_NODE_DIR  =  _PATH_VARRUN



                                                                 564

_______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___
Where to write socket.


GPM_NODE_DIR_MODE  =  0775


Mode of socket.


GPM_NODE_FIFO  =  '/dev/gpmdata'


FIFO name


GPM_NODE_PID  =  '/var/run/gpm.pid'


Name of PID file.


GPM_RGT  =  8


Right side of area.


GPM_SINGLE  =  16


Mouse single click event.


GPM_TOP  =  1


Top of area.


GPM_TRIPLE  =  64


Mouse triple click event.


GPM_UP  =  8


Mouse button up event.


_PATH_DEV  =  '/dev/'


Location of  /dev directory.


_PATH_VARRUN  =  '/var/run/'


Location of run PID files directory.
11.3.2         Types

Pgpmconnect  =  Pgpm_connect


Pointer to TGpmConnect (567  ) record.


Pgpmevent  =  Pgpm_event
                                                                 565

_______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___
Pointer to TGpmEvent (567  ) record


Pgpmroi  =  Pgpm_roi


Pointer to TGpmRoi (567  ) record.


Pgpm_connect  =  ^TGpm_connect


Pointer to TGpm_Connect (567  ) record.


Pgpm_event  =  ^Tgpm_event


Pointer to TGpm_Event (567  ) record


Pgpm_roi  =  ^Tgpm_roi


Pointer to Tgpm_roi (567  ) record.


Tgpmconnect  =  Tgpm_connect


Alias for TGpm_Connect (567  ) record.


TGpmEtype  =  LongInt


Type for event type.


Tgpmevent  =  Tgpm_event


Alias for TGPM_EVent (567  ) record


TGpmHandler  =  function(var  event:  Tgpmevent;clientdata:  pointer)
                                       :  LongInt


Mouse event handler callback.


TGpmMargin  =  LongInt


Type to hold area margin.


Tgpmroi  =  Tgpm_roi


Alias for TGpm_roi (567  )Record


Tgpm_connect  =  packed  record
   eventMask  :  Word;
   defaultMask  :  Word;
   minMod  :  Word;
   maxMod  :  Word;
   pid  :  LongInt;
   vc  :  LongInt;
end

                                                                 566

_______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___
GPM server connection information.


Tgpm_event  =  packed  record
   buttons  :  Byte;
   modifiers  :  Byte;
   vc  :  Word;
   dx  :  Word;
   dy  :  Word;
   x  :  Word;
   y  :  Word;
   EventType  :  TGpmEtype;
   clicks  :  LongInt;
   margin  :  TGpmMargin;
   wdx  :  Word;
   wdy  :  Word;
end
Tgpm_event describes the events that are reported by GPM.


Tgpm_roi  =  packed  record
   xmin  :  Integer;
   xmax  :  Integer;
   ymin  :  Integer;
   ymax  :  Integer;
   minmod  :  Word;
   maxmod  :  Word;
   eventmask  :  Word;
   owned  :  Word;
   handler  :  TGpmHandler;
   clientdata  :  pointer;
   prev  :  Pgpm_roi;
   next  :  Pgpm_roi;
end
Record used to define regions of interest.
11.3.3         Variables

gpm_current_roi  :  Pgpm_roi


Internal gpm library variable.  Do not use.


gpm_handler  :  TGpmHandler


Internal gpm library variable.  Do not use.


gpm_roi  :  Pgpm_roi


Internal gpm library variable.  Do not use.


gpm_roi_data  :  pointer



                                                                 567

                _______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________
                Internal gpm library variable.  Do not use.


                gpm_roi_handler  :  TGpmHandler


                Internal gpm library variable.  Do not use.
                11.4          Procedures  and  functions



                11.4.1         Gpm__AnyDouble

    Synopsis:    Check whether event has double click event.

Declaration:     function  Gpm_AnyDouble(EventType:  LongInt)  :  Boolean

    Visibility:   default

Description:     Gpm_AnyDouble returns True if  EventType contains the GPM_DOUBLE flag, False otherwise.

       Errors:   None.

    See also:    Gpm_StrictSingle (573  ), Gpm_AnySingle (568  ), Gpm_StrictDouble (573  ), Gpm_StrictTriple
                (573  ), Gpm_AnyTriple (568  )
                11.4.2         Gpm__AnySingle

    Synopsis:    Check whether event has a single click event.

Declaration:     function  Gpm_AnySingle(EventType:  LongInt)  :  Boolean

    Visibility:   default

Description:     Gpm_AnySingle returns True if  EventType contains the GPM_SINGLE flag, False otherwise.

       Errors:   None.

    See also:    Gpm_StrictSingle (573  ), Gpm_AnyDouble (568  ), Gpm_StrictDouble (573  ), Gpm_StrictTriple
                (573  ), Gpm_AnyTriple (568  )
                11.4.3         Gpm__AnyTriple

    Synopsis:    Check whether event has a triple click event.

Declaration:     function  Gpm_AnyTriple(EventType:  LongInt)  :  Boolean

    Visibility:   default

Description:     Gpm_AnySingle returns True if  EventType contains the GPM_TRIPLE flag, False otherwise.

       Errors:   None.

    See also:    Gpm_StrictSingle (573  ), Gpm_AnyDouble (568  ), Gpm_StrictDouble (573  ), Gpm_StrictTriple
                (573  ), Gpm_AnySingle (568  )



                                                                                 568

                _______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________
                11.4.4         gpm__close

    Synopsis:    Close connection to GPM server.

Declaration:     function  gpm_close  :  LongInt

    Visibility:   default

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.

                for an example, see Gpm_GetEvent (569  ).

       Errors:   None.

    See also:    Gpm_Open (571  )
                11.4.5         gpm__fitvalues

    Synopsis:    Change coordinates to fit physical screen.

Declaration:     function  gpm_fitvalues(var  x:  LongInt;var  y:  LongInt)  :  LongInt

    Visibility:   default

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 (569  )
                11.4.6         gpm__fitvaluesM

    Synopsis:    Change coordinates to fit margin.

Declaration:     function  gpm_fitvaluesM(var  x:  LongInt;var  y:  LongInt;margin:  LongInt)
                                                        :  LongInt

    Visibility:   default

Description:     Gpm_FitValuesM changes 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 (569  )
                11.4.7         gpm__getevent

    Synopsis:    Get event from event queue.

Declaration:     function  gpm_getevent(var  event:  Tgpm_event)  :  LongInt

    Visibility:   default

                                                                                 569

                _______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________
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:    Gpm_GetSnapshot (571  )


                Listing:  ./gpmex/gpmex.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       gpmex    ;


                {
                    Example       p r o g r a m t o  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        o r  GPM_DRAG        o r GPM_DOWN         o r 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.' ) ;
                       H a l t ( 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 t o  end  . ' ) ;
                    Repeat
                        g p m _g e t e v e n(tE 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 sand    G p m _b _l e f t )<>0    then
                                  w r i t e( 'l e f t  ' ) ;
                               i f  ( b u t t o n sand    G p m _b _r i g h t)<>0     then
                                  w r i t e( 'r i g h t  ' ) ;
                               i f  ( b u t t o n sand    G p m _b _m i d d l e)<>0     then
                                  Write    ( 'm i d d l e  ') ;
                              Write    ( ' )  E v e n t  :  ' ) ;
                              Case     E v e n t T y p eand    $F    o f
                                 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 sand     g p m _b _r i g h t)<>0;
                    g p m _c l o s e;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 570

                _______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________
                11.4.8         gpm__getsnapshot

    Synopsis:    Return servers' current image of mouse state.

Declaration:     function  gpm_getsnapshot(eptr:  Pgpmevent)  :  LongInt
                function  gpm_getsnapshot(var  eptr:  Tgpmevent)  :  LongInt

    Visibility:   default

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 function returns the number of mouse buttons, or -1 if this information is not available.

       Errors:   None.

    See also:    Gpm_GetEvent (569  )
                11.4.9         gpm__lowerroi

    Synopsis:    Lower a region of interest in the stack.

Declaration:     function  gpm_lowerroi(which:  Pgpm_roi;after:  Pgpm_roi)  :  Pgpm_roi

    Visibility:   default

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 (572  ), Gpm_PopRoi (572  ), Gpm_PushRoi (572  )
                11.4.10          gpm__open

    Synopsis:    Open connection to GPM server.

Declaration:     function  gpm_open(var  conn:  Tgpm_connect;flag:  LongInt)  :  LongInt

    Visibility:   default

Description:     Gpm_Open opens a new connection to the mouse server.  The connection is described by the
                fields of the conn record of type TGPMConnect (567  ).

                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.

                for an example, see Gpm_GetEvent (569  ).

       Errors:   On Error, the return value is -1.

    See also:    Gpm_Open (571  )
                                                                                 571

                _______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________
                11.4.11          gpm__poproi

    Synopsis:    Pop region of interest from the stack.

Declaration:     function  gpm_poproi(which:  Pgpm_roi)  :  Pgpm_roi

    Visibility:   default

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 (572  ), Gpm_LowerRoi (571  ), Gpm_PushRoi (572  )
                11.4.12          gpm__pushroi

    Synopsis:    Push region of interest on the stack.

Declaration:     function  gpm_pushroi(x1:  LongInt;y1:  LongInt;x2:  LongInt;y2:  LongInt;
                                                 mask:  LongInt;fun:  TGpmHandler;xtradata:  pointer)
                                                   :  Pgpm_roi

    Visibility:   default

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 (572  ), Gpm_PopRoi (572  ), Gpm_LowerRoi (571  )
                11.4.13          gpm__raiseroi

    Synopsis:    Raise region of interest in the stack.

Declaration:     function  gpm_raiseroi(which:  Pgpm_roi;before:  Pgpm_roi)  :  Pgpm_roi

    Visibility:   default

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 (572  ), Gpm_PopRoi (572  ), Gpm_LowerRoi (571  )
                11.4.14          gpm__repeat

    Synopsis:    Check for presence of mouse event.

Declaration:     function  gpm_repeat(millisec:  LongInt)  :  LongInt

    Visibility:   default

Description:     Gpm_Repeat returns 1 of no mouse event arrives in the next millisec miiliseconds, it returns
                0 otherwise.



                                                                                 572

                _______________________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________
       Errors:   None.

    See also:    Gpm_GetEvent (569  )
                11.4.15          Gpm__StrictDouble

    Synopsis:    Check whether event contains only a double-click event.

Declaration:     function  Gpm_StrictDouble(EventType:  LongInt)  :  Boolean

    Visibility:   default

Description:     Gpm_StrictDouble returns true if EventType contains only a doubleclick event, False oth-
                erwise.

       Errors:   None.

    See also:    Gpm_StrictSingle  (573  ),  Gpm_AnyTriple  (568  ),  Gpm_AnyDouble  (568  ),  Gpm_StrictTriple
                (573  ), Gpm_AnySingle (568  )
                11.4.16          Gpm__StrictSingle

    Synopsis:    Check whether event contains only a single-click event.

Declaration:     function  Gpm_StrictSingle(EventType:  LongInt)  :  Boolean

    Visibility:   default

Description:     Gpm_StrictDouble returns True if EventType contains only a singleclick event, False oth-
                erwise.

       Errors:   None.

    See also:    Gpm_AnyTriple (568  ), Gpm_StrictDouble (573  ), Gpm_AnyDouble (568  ), Gpm_StrictTriple
                (573  ), Gpm_AnySingle (568  )
                11.4.17          Gpm__StrictTriple

    Synopsis:    Check whether event contains only a triple-click event.

Declaration:     function  Gpm_StrictTriple(EventType:  LongInt)  :  Boolean

    Visibility:   default

Description:     Gpm_StrictTriple returns true if  EventType contains only a triple click event, False oth-
                erwise.

       Errors:   None.

    See also:    Gpm_AnyTriple (568  ), Gpm_StrictDouble (573  ), Gpm_AnyDouble (568  ), Gpm_StrictSingle
                (573  ), Gpm_AnySingle (568  )



                                                                                 573


Chapter   12


Reference   for   unit   'Graph'
12.1          Categorized  functions:   Text  and  font  handling


Functions to set texts on the screen.



                                                       Table 12.1:

                  __Name________________________________Description_________________________________________
                    GetTextSettings (609  )            Get current text settings
                    InstallUserFont (612  )            Install a new font
                    OutText (614  )                    Write text at current cursor position
                    OutTextXY (600  )                  Write text at coordinates X,Y
                    RegisterBGIFont (615  )            Register a new font
                    SetTextJustify (618  )             Set text justification
                    SetTextStyle (619  )               Set text style
                    SetUserCharSize (620  )            Set text size
                    TextHeight (621  )                 Calculate height of text
                    TextWidth (621  )                  Calculate width of text



12.2          Categorized  functions:   Filled  drawings


Functions for drawing filled regions.
12.3          Categorized  functions:   Drawing  primitives


Functions for simple drawing.
12.4          Categorized  functions:   Color  management


All functions related to color management.
                                                             574

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___

                                                       Table 12.2:

                         __Name_____________________________Description______________________________
                           Bar3D (602  )                    Draw a filled 3D-style bar
                           Bar (602  )                      Draw a filled rectangle
                           FloodFill (604  )                Fill starting from coordinate
                           FillEllipse (604  )              Draw a filled ellipse
                           FillPoly (604  )                 Draw a filled polygone
                           GetFillPattern (606  )           Get current fill pattern
                           GetFillSettings (607  )          Get current fill settings
                           SetFillPattern (617  )           Set current fill pattern
                           SetFillStyle (617  )             Set current fill settings

                                                       Table 12.3:

        __Name______________________________Description_______________________________________________________________
          Arc (602  )                       Draw an arc
          Circle (599  )                    Draw a complete circle
          DrawPoly (603  )                  Draw a polygone with N points
          Ellipse (604  )                   Draw an ellipse
          GetArcCoords (605  )              Get arc coordinates
          GetLineSettings (607  )           Get current line drawing settings
          Line (600  )                      Draw line between 2 points
          LineRel (612  )                   Draw line relative to current position
          LineTo (613  )                    Draw line from current position to absolute position
          MoveRel (613  )                   Move cursor relative to current position
          MoveTo (613  )                    Move cursor to absolute position
          PieSlice (614  )                  Draw a pie slice
          PutPixel (601  )                  Draw 1 pixel
          Rectangle (614  )                 Draw a non-filled rectangle
          Sector (615  )                    Draw a sector
          SetLineStyle (618  )              Set current line drawing style

12.5          Categorized  functions:   Screen  management


General drawing screen management functions.
12.6          Categorized  functions:   Initialization


Initialization of the graphics screen.
12.7          Target  specific  issues:   Linux


There are several issues on Linux that need to be taken care of:

The Linux version of the Graph unit uses the libvga library.  This library works on the console,
not under X.

If you get an error similar to
                                                                 575

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___

                                                       Table 12.4:

                  __Name_________________________________Description________________________________________
                    GetBkColor (605  )                   Get current background color
                    GetColor (605  )                     Get current foreground color
                    GetDefaultPalette (606  )            Get default palette entries
                    GetMaxColor (607  )                  Get maximum valid color
                    GetPaletteSize (609  )               Get size of palette for current mode
                    GetPixel (600  )                     Get color of selected pixel
                    GetPalette (609  )                   Get palette entry
                    SetAllPalette (601  )                Set all colors in palette
                    SetBkColor (616  )                   Set background color
                    SetColor (616  )                     Set foreground color
                    SetPalette (618  )                   Set palette entry
                    SetRGBPalette (601  )                Set palette entry with RGB values

                                                       Table 12.5:

                   _Name_______________________________Description___________________________________________
                     ClearViewPort (599  )              Clear the current viewport
                     GetImage (600  )                   Copy image from screen to memory
                     GetMaxX (608  )                    Get maximum X coordinate
                     GetMaxY (608  )                    Get maximum Y coordinate
                     GetX (610  )                       Get current X position
                     GetY (610  )                       Get current Y position
                     ImageSize (600  )                  Get size of selected image
                     GetViewSettings (610  )            Get current viewport settings
                     PutImage (601  )                   Copy image from memory to screen
                     SetActivePage (601  )              Set active video page
                     SetAspectRatio (616  )             Set aspect ratio for drawing routines
                     SetViewPort (620  )                Set current viewport
                     SetVisualPage (601  )              Set visual page
                     SetWriteMode (620  )               Set write mode for screen operations

/usr/bin/ld:  cannot  find  -lvga


This can mean one of two things:  either libvga and it's development package is not installed
properly, or the directory where it is installed is not in the linker path.

To remedy the former, you should install both the libvga package and libvga-devel package
(or compile and install from scratch).

To remedy the latter, you should add the path to the compiler command-line using the -Fl
option.

Programs using libvga need root privileges to run.  You can make them setuid root with the
following command:


chown  root.root  myprogram
chmod  u+s  myprogram


The libvga library will give up the root privileges after it is initialized.



                                                                 576

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___

                                                       Table 12.6:

            __Name__________________________________Description___________________________________________________
              ClearDevice (603  )                   Empty the graphics screen
              CloseGraph (603  )                    Finish drawing session, return to text mode
              DetectGraph (603  )                   Detect graphical modes
              GetAspectRatio (605  )                Get aspect ratio of screen
              GetModeRange (609  )                  Get range of valid modes for current driver
              GraphDefaults (610  )                 Set defaults
              GetDriverName (606  )                 Return name of graphical driver
              GetGraphMode (607  )                  Return current or last used graphics mode
              GetMaxMode (608  )                    Get maximum mode for current driver
              GetModeName (608  )                   Get name of current mode
              GraphErrorMsg (611  )                 String representation of graphical error
              GraphResult (611  )                   Result of last drawing operation
              InitGraph (611  )                     Initialize graphics drivers
              InstallUserDriver (612  )             Install a new driver
              RegisterBGIDriver (615  )             Register a new driver
              RestoreCRTMode (615  )                Go back to text mode
              SetGraphMode (617  )                  Set graphical mode

there is an experimental version of the Graphics library available that uses GGI to do all the
drawing, but it is not well tested.  It's called ggigraph and is distributed in source form only.

Do  not  use  the  CRT  unit  together  with  the  Graph  unit:  the  console  may  end  up  in  an
unusable state.  Instead, the ncurses unit may function fine.
12.8          Target  specific  issues:   DOS


VESA  modes  (i.e.,  anything  but  320x200x256  and  640x480x16)  do  not  work  under  most
installations of Windows NT, Windows 2000 and Windows XP. They also do not work for
some  people  under  Windows  98  and  Windows  ME,  depending  on  their  graphics  drivers.
However, the graph unit cannot detect this, because no errors are returned from the system.
In such cases, the screen simply turns black, or will show garbage.

Nothing  can  be  done  about  this,  the  reason  is  missing  or  buggy  support  in  the  graphics
drivers of the operating system.
12.9          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.



                                                                 577

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
In this section we give a short explanation of the new mode system.  the following drivers
were defined:


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 below example.

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 second example below.



                                                                 578

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
Thus, the getmoderange function can be used to detect all available modes and drivers, as
in the third example below:
12.10            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).
12.11            Overview


This document describes the GRAPH unit for Free Pascal, for all platforms.  The unit was first
written for dos by Florian klaempfl, but was later completely rewritten by Carl-Eric Codere to
be completely portable.  The unit is provided for compatibility only: It is recommended to use
more modern graphical systems.  The graph unit will allow to recompile old programs, they
will work to some extent, but if the application has heavy graphical needs, it's recommended
to use another set of graphical routines, suited to the platform the program should work on.
12.12            Constants,  types  and  variables



12.12.1          Constants

AndPut  =  3


Draw operation:  use AND


AnsiToASCIITransTable  :  TCharsetTransTable  =  (#$00,#$01,#$02,#$03,#$04,#$05,#$06,#$07,#$08,#$09,#$0a,#$0b,#$0c,#$0d,#$0e,#$0f,#*
 *$10,#$11,#$12,#$13,#$14,#$15,#$16,#$17,#$18,#$19,#$1a,#$1b,#$1c,#$1d,#$1e,#$1f,#$20,#$21,#$22,#$23,#$24,#$25,#$26,#$27,#$28,#$29,*
 *#$2a,#$2b,#$2c,#$2d,#$2e,#$2f,#$30,#$31,#$32,#$33,#$34,#$35,#$36,#$37,#$38,#$39,#$3a,@


Default ansi transliteration table.


BkSlashFill  =  5


Fill style:  Diagonal (backslash) lines


black  =  0


Color code:  black.


blue  =  1


Color code:  blue


BoldFont  =  10


Font number:  Bold font.


BottomText  =  0


Vertical text alignment:  Align text to bottom



                                                                 579

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
brown  =  6


Color code:  brown


CenterLn  =  2


Line style:  centered line


CenterText  =  1


Horizontal text alignment:  Center text


ClipOff  =  false


Viewport clipping off


ClipOn  =  true


Viewport clipping on


CloseDotFill  =  11


Fill style:  Closely spaced dotted lines


CopyPut  =  0


Draw operation:  use Copy


CurrentDriver  =  -128


Currently used driver


cyan  =  3


Color code:  Cyan


D12bit  =  16


Mode:  Depth 12 bit


D15bit  =  17


Mode:  Depth 15 bit


D16bit  =  18


Mode:  Depth 16 bit


D1bit  =  11


Mode:  Depth 1 bit



                                                                 580

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
D24bit  =  19


Mode:  Depth 24 bit


D2bit  =  12


Mode:  Depth 2 bit


D32bit  =  20


Mode:  Depth 32 bit


D4bit  =  13


Mode:  Depth 4 bit


D64bit  =  21


Mode:  Depth 64 bit


D6bit  =  14


Mode:  Depth 6 bit


D8bit  =  15


Mode:  Depth 8 bit


darkgray  =  8


Color code:  Dark gray


DashedLn  =  3


Line style:  dashed line


Default  =  0


Default mode


DefaultFont  =  0


Font number:  Normal font


Detect  =  0


Mode:  Detect mode.


detectMode  =  30000


Mode:  Autodetect optimal mode



                                                                 581

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
DottedLn  =  1


Line style:  Dotted line


DrawTextBackground  :  Boolean  =  false


Should the background of texts be drawn or should it be left untouched ?


EGABlack  =  0


Color code:  EGA Black


EGABlue  =  1


Color code:  EGA blue


EGABrown  =  20


Color code:  EGA brown


EGACyan  =  3


Color code:  EGA cyan


EGADarkgray  =  56


Color code:  EGA dark gray


EGAGreen  =  2


Color code:  EGA green


EGALightblue  =  57


Color code:  EGA Light blue


EGALightcyan  =  59


Color code:  EGA Light cyan


EGALightgray  =  7


Color code:  EGA Light gray


EGALightgreen  =  58


Color code:  EGA Light green


EGALightmagenta  =  61


Color code:  EGA light magenta



                                                                 582

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
EGALightred  =  60


Color code:  EGA light red


EGAMagenta  =  5


Color code:  EGA magenta


EGARed  =  4


Color code:  EGA red


EGAWhite  =  63


Color code:  EGA white


EGAYellow  =  62


Color code:  EGA yellow


EmptyFill  =  0


Fill style:  Do not fill


EuroFont  =  9


Font number:  ?


fillpatternTable  :  Array[0..12]  of  FillPatternType  =  (  (  $00,$00,$00,$00,$00,$00,$00,$00  )  ,  (  $ff,$ff,$ff,$ff,$ff,$ff,*
 *$ff,$ff  )  ,  (  $ff,$ff,$00,$00,$ff,$ff,$00,$00  )  ,  (  $01,$02,$04,$08,$10,$20,$40,$80  )  ,  (  $07,$0e,$1c,$38,$70,$e0,$c1*
 *,$83  )  ,  (  $07,$83,$c1,$e0,$70,$38,$1c,$0e  )  ,  (  $5a,$2d,$96,$4b,$a5,$d2,$69,@


Table with standard fill patterns


G1024x768x16  =  30


Mode:  Resolution 1024x768, 16 colors


G1024x768x16M  =  25


Mode:  Resolution 1024x768, 16M colors


G1024x768x16M32  =  36


Mode:  Resolution 1024x758, 16M 32-bit colors


G1024x768x256  =  12


Mode:  Resolution 1024x768, 256 colors


G1024x768x32K  =  23


Mode:  Resolution 1024x768, 32K colors



                                                                 583

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
G1024x768x64K  =  24


Mode:  Resolution 1024x768, 64K colors


G1152x864x16  =  38


Mode:  Resolution 1152x864, 16 colors


G1152x864x16M  =  42


Mode:  Resolution 1152x864, 16M colors


G1152x864x16M32  =  43


Mode:  Resolution 1152x864, 16M 32-bitcolors


G1152x864x256  =  39


Mode:  Resolution 1152x864, 256 colors


G1152x864x32K  =  40


Mode:  Resolution 1152x864, 32K colors


G1152x864x64K  =  41


Mode:  Resolution 1152x864, 64K colors


G1280x1024x16  =  31


Mode:  Resolution 1280x1024, 16 colors


G1280x1024x16M  =  28


Mode:  Resolution 1280x1024, 16M colors


G1280x1024x16M32  =  37


Mode:  Resolution 1280x1024, 16M 32-bit colors


G1280x1024x256  =  13


Mode:  Resolution 1280x1024, 256 colors


G1280x1024x32K  =  26


Mode:  Resolution 1280x1024, 32K colors


G1280x1024x64K  =  27


Mode:  Resolution 1280x1024, 64K colors



                                                                 584

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
G1600x1200x16  =  44


Mode:  Resolution 1600x1200, 16 colors


G1600x1200x16M  =  48


Mode:  Resolution 1600x1200, 16M colors


G1600x1200x16M32  =  49


Mode:  Resolution 1600x1200, 16M 32-bit colors


G1600x1200x256  =  45


Mode:  Resolution 1600x1200, 256 colors


G1600x1200x32K  =  46


Mode:  Resolution 1600x1200, 32K colors


G1600x1200x64K  =  47


Mode:  Resolution 1600x1200, 64K colors


G320x200x16  =  1


Mode:  Resulution 320x200, 16 colors


G320x200x16M  =  16


Mode:  Resolution 320x200, 16M colors


G320x200x16M32  =  33


Mode:  Resolution 320x200, 16M 32-bit colors


G320x200x256  =  5


Mode:  Resolution 320x200, 256 colors


G320x200x32K  =  14


Mode:  Resolution 320x200, 32K colors


G320x200x64K  =  15


Mode:  Resolution 320x200, 64K colors


G320x240x256  =  6


Mode:  Resolution 320x240, 256 colors



                                                                 585

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
G320x400x256  =  7


Mode:  Resolution 320x400, 256 colors


G360x480x256  =  8


Mode:  Resolution 360x480, 256 colors


G640x200x16  =  2


Mode:  Resolution x, colors


G640x350x16  =  3


Mode:  Resolution x, colors


G640x480x16  =  4


Mode:  Resolution x, colors


G640x480x16M  =  19


Mode:  Resolution 640x480, 16M colors


G640x480x16M32  =  34


Mode:  Resolution 640x480, 16M 32-bit colors


G640x480x2  =  9


Mode:  Resolution 640x480, 2 colors


G640x480x256  =  10


Mode:  Resolution 640x480, 256 colors


G640x480x32K  =  17


Mode:  Resolution 640x480, 32K colors


G640x480x64K  =  18


Mode:  Resolution 640x480, 64K colors


G720x348x2  =  32


Mode:  Resolution 720x348, 2 colors


G800x600x16  =  29


Mode:  Resolution 800x600, 16 colors



                                                                 586

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
G800x600x16M  =  22


Mode:  Resolution 800x600, 16M colors


G800x600x16M32  =  35


Mode:  Resolution 800x600, 16M 32-bit colors


G800x600x256  =  11


Mode:  Resolution 800x600, 256 colors


G800x600x32K  =  20


Mode:  Resolution 800x600, 32K colors


G800x600x64K  =  21


Mode:  Resolution 800x600, 64K colors


GothicFont  =  4


Font number:  Gothic font


GraphStringTransTable  :  PCharsetTransTable  =  nil


Table used when transliterating strings.


green  =  2


Color code:  green


grError  =  -11


Error:  Unknown error.


grFileNotFound  =  -3


Error:  File for driver not found.


grFontNotFound  =  -8


Error:  font description file not found.


grInvalidDriver  =  -4


Error:  Invalid driver specified


grInvalidFont  =  -13


Error:  Invalid font description



                                                                 587

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
grInvalidFontNum  =  -14


Error:  Invalid font number


grInvalidMode  =  -10


Error:  Invalid mode specified.


grInvalidVersion  =  -18


Error:  Invalid version.


grIOerror  =  -12


Error:  Unspecified Input/Output error.


grNoFloodMem  =  -7


Error:  Could not allocate memory for flood operation.


grNoFontMem  =  -9


Error:  Not enough memory to load font.


grNoInitGraph  =  -1


Error:  Graphical system not initialized


grNoLoadMem  =  -5


Error:  Memory error.


grNoScanMem  =  -6


Error:  Could not allocate memory for scan


grNotDetected  =  -2


Error:  Graphics device not detected.


grOk  =  0


Graphical operation went OK.


HatchFill  =  7


Fill style:  Hatch lines


HercMono  =  7


Mode:  Hercules, mono color



                                                                 588

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
HercMonoHi  =  0


Mode:  Hercules card, monochrome, high resolution


highNewDriver  =  21


Mode:  highest number for new driver


highNewMode  =  30015


Mode:  Highest possible value of the new modes.


HorizDir  =  0


Text write direction:  Horizontal


InterleaveFill  =  9


Fill style:  Interleaving lines


LCOMFont  =  8


Font number:  ?


LeftText  =  0


Horizontal text alignment:  Align text left


lightblue  =  9


Color code:  Light blue


lightcyan  =  11


Color code:  Light cyan


lightgray  =  7


Color code:  Light gray


lightgreen  =  10


Color code:  Light green


lightmagenta  =  13


Color code:  Light magenta


lightred  =  12


Color code:  Light red



                                                                 589

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
LineFill  =  2


Fill style:  Fill using horizontal lines


lowNewDriver  =  11


Mode:  lowest number for new driver


lowNewMode  =  30001


Mode:  Lowest possible value of the new modes.


LowRes  =  1


Mode:  Low resolution.


LtBkSlashFill  =  6


Fill style:  Light diagonal (backslash) lines


LtSlashFill  =  3


Fill style:  Light diagonal (slash) lines


m1024x768  =  30012


Mode:  Resolution 1024x768


m1280x1024  =  30013


Mode:  Resolution 1280x1024


m1600x1200  =  30014


Mode:  Resolution 1600x1200


m2048x1536  =  30015


Mode:  Resolution 2048x1536


m320x200  =  30001


Mode:  Resolution 320x200


m320x256  =  30002


Mode:  Resolution 320x256


m320x400  =  30003


Mode:  Resolution 320x400



                                                                 590

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
m512x384  =  30004


Mode:  Resolution 512x384


m640x200  =  30005


Mode:  Resolution 640x200


m640x256  =  30006


Mode:  Resolution 640x256


m640x350  =  30007


Mode:  Resolution 640x350


m640x400  =  30008


Mode:  Resolution 640x400


m640x480  =  30009


Mode:  Resolution 640x480


m800x600  =  30010


Mode:  Resolution 800x600


m832x624  =  30011


Mode:  Resolution 832x624


magenta  =  5


Color code:  Magenta


MaxColors  =  255


Max amount of colors in a palette


maxsmallint  =  high  (  smallint  )


Maximum value for smallint type


NormalPut  =  0


Draw operation:  Use Normal (copy) operation


NormWidth  =  1


Line width:  Normal width



                                                                 591

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
NotPut  =  4


Draw operation:  use NOT


OrPut  =  2


Draw operation:  use OR


red  =  4


Color code:  Red


resolutions  :  Array[lowNewMode..highNewMode]  of  TResolutionRec  =  (  (  x:320;y:200  )  ,  (  x:320;y:256  )  ,  (  x:320;y:40*
 *0  )  ,  (  x:512;y:384  )  ,  (  x:640;y:200  )  ,  (  x:640;y:256  )  ,  (  x:640;y:350  )  ,  (  x:640;y:400  )  ,  (  x:640;y*
 *:480  )  ,  (  x:800;y:600  )  ,  (  x:832;y:624  )  ,  (  x:1024;y:768  )  ,  (  x:1@


Array with actual resolutions of the new modes


RightText  =  2


Horizontal text alignment:  Align text right


SansSerifFont  =  3


Font number:  Sans Serif font


ScriptFont  =  5


Font number:  Script font


SimpleFont  =  6


Font number:  Simple font


SlashFill  =  4


Fill style:  Diagonal (slash) lines


SmallFont  =  2


Font number:  Small font


SolidFill  =  1


Fill style:  Solid fill.


SolidLn  =  0


Line style:  Solid line


ThickWidth  =  3


Line width:  double width



                                                                 592

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
TopOff  =  false


Top off


TopOn  =  true


Top on


TopText  =  2


Vertical text alignment:  Align text to top


TriplexFont  =  1


Font number:  Triplex font


TSCRFont  =  7


Font number:  Terminal font


UserBitLn  =  4


Line style:  User defined


UserCharSize  =  0


User character size


UserFill  =  12


Fill style:  User-defined fill.


VertDir  =  1


Text write direction:  Vertical


VESA  =  10


Mode:  VESA graphics adaptor.


VGA  =  9


Mode:  VGA graphics adaptor.


VGAHi  =  2


Mode:  VGA high resolution (640x480)


VGALo  =  0


Mode:  VGA low resolution (640x200)



                                                                 593

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
VGAMed  =  1


Mode:  VGA medium resolution (640x350)


white  =  15


Color code:  White


WideDotFill  =  10


Fill style:  Widely spaced dotted lines


XHatchFill  =  8


Fill style:  Heavy hatch lines


XORPut  =  1


Draw operation:  use XOR


yellow  =  14


Color code:  Yellow
12.12.2          Types

ArcCoordsType  =  record
    x  :  SmallInt;
    y  :  SmallInt;
    xstart  :  SmallInt;
    ystart  :  SmallInt;
    xend  :  SmallInt;
    yend  :  SmallInt;
end
Describe the last arc which was drawn on screen


CircleProc  =  procedure(X:  SmallInt;Y:  SmallInt;Radius:  Word)


Standard circle drawing routine prototype.


clrviewproc  =  procedure


Standard clearviewport routine prototype


defpixelproc  =  procedure(X:  SmallInt;Y:  SmallInt)


This is the standard putpixel routine used by all function drawing routines, it will use the
viewport settings,  as well as clip,  and use the current foreground color to plot the desired
pixel.



                                                                 594

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
ellipseproc  =  procedure(X:  SmallInt;Y:  SmallInt;XRadius:  Word;
                                       YRadius:  Word;stAngle:  Word;EndAngle:  Word;
                                       fp:  patternlineproc)


Standard ellipse drawing routine prototype.


FillPatternType  =  Array[1..8]  of  Byte


Bit pattern used when drawing lines.  Set bits are drawn.


FillSettingsType  =  record
   pattern  :  Word;
   color  :  Word;
end
Record describing fill mode


getimageproc  =  procedure(X1:  SmallInt;Y1:  SmallInt;X2:  SmallInt;
                                         Y2:  SmallInt;var  Bitmap)


Standard GetImage (600  ) procedure prototype.


getpixelproc  =  function(X:  SmallInt;Y:  SmallInt)  :  Word


Standard pixel fetching routine prototype


getrgbpaletteproc  =  procedure(ColorNum:  SmallInt;var  RedValue:  SmallInt;
                                                 var  GreenValue:  SmallInt;
                                                 var  BlueValue:  SmallInt)


This routine prototype is a hook for GetRGBPalette (600  )


getscanlineproc  =  procedure(X1:  SmallInt;X2:  SmallInt;Y:  SmallInt;
                                              var  data)


This routine is used for FloodFill (604  ) It returns an entire screen scan line with a word for
each pixel in the scanline.  Also handy for GetImage.


graphfreememprc  =  procedure(var  P:  Pointer;size:  Word)


Procedure prototype, used when heap memory is freed by the graph routines.


graphgetmemprc  =  procedure(var  P:  pointer;size:  Word)


Procedure prototype, used when heap memory is needed by the graph routines.


graph_float  =  single


The platform's preferred floating point size for fast graph operations
                                                                 595

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
hlineproc  =  procedure(x:  SmallInt;x2:  SmallInt;y:  SmallInt)


Standard procedure prototype to draw a single horizontal line


imagesizeproc  =  function(X1:  SmallInt;Y1:  SmallInt;X2:  SmallInt;
                                         Y2:  SmallInt)  :  LongInt


Standard ImageSize (600  ) calculation procedure prototype.


initmodeproc  =  procedure


Standard routine prototype to initialize a mode.


lineproc  =  procedure(X1:  SmallInt;Y1:  SmallInt;X2:  SmallInt;
                                  Y2:  SmallInt)


Standard line drawing routine prototype.


LineSettingsType  =  record
   linestyle  :  Word;
   pattern  :  Word;
   thickness  :  Word;
end
Record describing current line drawing mode


OutTextXYProc  =  procedure(x:  SmallInt;y:  SmallInt;
                                          const  TextString:  String)


This routine prototype is a hook for OutTextXY (600  )


PaletteType  =  record
   Size  :  LongInt;
   Colors  :  Array[0..MaxColors]  of  RGBRec;
end
Record describing palette.


patternlineproc  =  procedure(x1:  SmallInt;x2:  SmallInt;y:  SmallInt)


Standard procedure prototype to draw a patterned line


PCharsetTransTable  =  ^TCharsetTransTable


Pointer to TCharsetTransTable (598  ) array.


PModeInfo  =  ^TModeInfo


Pointer to TModeInfo (599  ) record



                                                                 596

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
PointType  =  record
   x  :  SmallInt;
   y  :  SmallInt;
end
Record describing a point in a 2 dimensional plane


putimageproc  =  procedure(X:  SmallInt;Y:  SmallInt;var  Bitmap;
                                         BitBlt:  Word)


Standard PutImage (601  ) procedure prototype.


putpixelproc  =  procedure(X:  SmallInt;Y:  SmallInt;Color:  Word)


Standard pixel drawing routine prototype


restorestateproc  =  procedure


Standard routine prototype to restore the graphical state at a closegraph call.


RGBRec  =  packed  record
   Red  :  SmallInt;
   Green  :  SmallInt;
   Blue  :  SmallInt;
end
Record describing palette RGB color


savestateproc  =  procedure


Standard routine prototype to save the graphical state before a mode is set.


setactivepageproc  =  procedure(page:  Word)


Standard SetActivePage (601  ) procedure prototype.


SetAllPaletteProc  =  procedure(const  Palette:  PaletteType)


This routine prototype is a hook for SetAllPalette (601  )


setrgbpaletteproc  =  procedure(ColorNum:  SmallInt;RedValue:  SmallInt;
                                                 GreenValue:  SmallInt;BlueValue:  SmallInt)


This routine prototype is a hook for SetRGBPalette (601  )


setvisualpageproc  =  procedure(page:  Word)


Standard SetVisualPage (601  ) procedure prototype.
                                                                 597

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
smallint  =  -32768..32767


Type redefinition


TCharsetTransTable  =  Array[Char]  of  Char


Character transliteration table, with entries for 256 characters


TextSettingsType  =  record
   font  :  Word;
   direction  :  Word;
   charsize  :  Word;
   horiz  :  Word;
   vert  :  Word;
end
Record describing how texts are drawn.


TModeInfo  =  record
   DriverNumber  :  SmallInt;
   ModeNumber  :  SmallInt;
   internModeNumber  :  SmallInt;
   MaxColor  :  LongInt;
   PaletteSize  :  LongInt;
   XAspect  :  Word;
   YAspect  :  Word;
   MaxX  :  Word;
   MaxY  :  Word;
   DirectColor  :  Boolean;
   Hardwarepages  :  Byte;
   ModeName  :  String;
   DirectPutPixel  :  defpixelproc;
   GetPixel  :  getpixelproc;
   PutPixel  :  putpixelproc;
   SetRGBPalette  :  setrgbpaletteproc;
   GetRGBPalette  :  getrgbpaletteproc;
   SetAllPalette  :  SetAllPaletteProc;
   SetVisualPage  :  setvisualpageproc;
   SetActivePage  :  setactivepageproc;
   ClearViewPort  :  clrviewproc;
   PutImage  :  putimageproc;
   GetImage  :  getimageproc;
   ImageSize  :  imagesizeproc;
   GetScanLine  :  getscanlineproc;
   Line  :  lineproc;
   InternalEllipse  :  ellipseproc;
   PatternLine  :  patternlineproc;
   HLine  :  hlineproc;
   VLine  :  vlineproc;
   Circle  :  CircleProc;
   InitMode  :  initmodeproc;
   OutTextXY  :  OutTextXYProc;



                                                                 598

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
   next  :  PModeInfo;
end
Record describing a graphical mode.


TNewModeInfo  =  record
   modeInfo  :  Array[lowNewDriver..highNewDriver]  of  PModeInfo;
   loHiModeNr  :  Array[lowNewDriver..highNewDriver]  of  ;
end
Mode information for new modes.a


TResolutionRec  =  record
   x  :  LongInt;
   y  :  LongInt;
end
Record describing resolution


ViewPortType  =  record
   x1  :  SmallInt;
   y1  :  SmallInt;
   x2  :  SmallInt;
   y2  :  SmallInt;
   Clip  :  Boolean;
end
Record describing a viewport


vlineproc  =  procedure(x:  SmallInt;y:  SmallInt;y2:  SmallInt)


Standard procedure prototype to draw a single vertical line
12.12.3          Variables

Circle  :  CircleProc


Circle draws a complete circle with center at (X,Y), radius radius.


ClearViewPort  :  clrviewproc


Clears  the  current  viewport.   The  current  background  color  is  used  as  filling  color.   The
pointer is set at (0,0).


DirectPutPixel  :  defpixelproc


Hook to directly draw a pixel on the screen.



                                                                 599

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
GetImage  :  getimageproc


GetImage Places a copy of the screen area (X1,Y1) to X2,Y2 in BitMap


GetPixel  :  getpixelproc


GetPixel returns the color of the point at (X,Y)


GetRGBPalette  :  getrgbpaletteproc


Hook to set a RGB palette entries.


GetScanLine  :  getscanlineproc


Hook to get a scan line from the screen.


GraphFreeMemPtr  :  graphfreememprc


Hook to free heap memory.


GraphGetMemPtr  :  graphgetmemprc


Hook to get heap memory


HLine  :  hlineproc


Hook to draw a solid horizontal line


ImageSize  :  imagesizeproc


ImageSize returns the number of bytes needed to store the image in the rectangle defined
by (X1,Y1) and (X2,Y2).


InternalEllipse  :  ellipseproc


Hook to draw an ellipse


Line  :  lineproc


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)


OutTextXY  :  OutTextXYProc


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.


PatternLine  :  patternlineproc


Hook to draw a patterned line



                                                                 600

___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___
PutImage  :  putimageproc


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 :


     o CopyPut

     o XORPut

     o ORPut

     o AndPut

     o NotPut


PutPixel  :  putpixelproc


Puts a point at (X,Y) using color Color


RestoreVideoState  :  restorestateproc


Hook to restore a saved video mode


SaveVideoState  :  savestateproc


Hook to save the current video state


SetActivePage  :  setactivepageproc


Sets Page as the active page for all graphical output.


SetAllPalette  :  SetAllPaletteProc


Sets the current palette to Palette.  Palette is an untyped variable, usually pointing to a
record of type PaletteType


SetRGBPalette  :  setrgbpaletteproc


SetRGBPalette sets the ColorNr-th entry in the palette to the color with RGB-values Red,
Green  Blue.


SetVisualPage  :  setvisualpageproc


SetVisualPage sets the video page to page number Page.


VLine  :  vlineproc


Hook to draw a solid vertical line


                                                                 601

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13            Procedures  and  functions



                12.13.1          Arc

    Synopsis:    Draw part of a circle

Declaration:     procedure  Arc(X:  SmallInt;Y:  SmallInt;StAngle:  Word;EndAngle:  Word;
                                      Radius:  Word)

    Visibility:   default

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 (599  ), Ellipse (604  ), GetArcCoords (605  ), PieSlice (614  ), Sector (615  )
                12.13.2          Bar

    Synopsis:    Draw filled rectangle

Declaration:     procedure  Bar(x1:  SmallInt;y1:  SmallInt;x2:  SmallInt;y2:  SmallInt)

    Visibility:   default

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 (602  ), Rectangle (614  )
                12.13.3          Bar3D

    Synopsis:    Draw filled 3-dimensional rectangle

Declaration:     procedure  Bar3D(x1:  SmallInt;y1:  SmallInt;x2:  SmallInt;y2:  SmallInt;
                                         depth:  Word;top:  Boolean)

    Visibility:   default

Description:     Bar3d 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 (602  ), Rectangle (614  )

                                                                                 602

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.4          ClearDevice

    Synopsis:    Clear the complete screen

Declaration:     procedure  ClearDevice

    Visibility:   default

Description:     Clears  the  graphical  screen  (with  the  current  background  color),  and  sets  the  pointer  at
                (0,0).

       Errors:   None.

    See also:    ClearViewPort (599  ), SetBkColor (616  )
                12.13.5          Closegraph

    Synopsis:    Close graphical system.

Declaration:     procedure  Closegraph

    Visibility:   default

Description:     Closes  the  graphical  system,  and  restores  the  screen  modus  which  was  active  before  the
                graphical modus was activated.

       Errors:   None.

    See also:    InitGraph (611  )
                12.13.6          DetectGraph

    Synopsis:    Detect correct graphical driver to use

Declaration:     procedure  DetectGraph(var  GraphDriver:  SmallInt;var  GraphMode:  SmallInt)

    Visibility:   default

Description:     DetectGraph 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 (611  )
                12.13.7          DrawPoly

    Synopsis:    Draw a polygone

Declaration:     procedure  DrawPoly(NumPoints:  Word;var  polypoints)

    Visibility:   default

Description:     DrawPoly  draws  a  polygone  with  NumberOfPoints  corner  points,  using  the  current  color
                and line-style.  PolyPoints is an array of type PointType (597  ).

       Errors:   None.

    See also:    Bar (602  ), Bar3D (602  ), Rectangle (614  )



                                                                                 603

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.8          Ellipse

    Synopsis:    Draw an ellipse

Declaration:     procedure  Ellipse(X:  SmallInt;Y:  SmallInt;stAngle:  Word;EndAngle:  Word;
                                            XRadius:  Word;YRadius:  Word)

    Visibility:   default

Description:     Ellipse draws part of an ellipse with center at (X,Y). XRadius and Yradius are the hori-
                zontal 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 (3 o'clock is
                equal to 0 degrees).  Only positive angles can be specified.

       Errors:   None.

    See also:    Arc (602  ), Circle (599  ), FillEllipse (604  )
                12.13.9          FillEllipse

    Synopsis:    Draw and fill an ellipse

Declaration:     procedure  FillEllipse(X:  SmallInt;Y:  SmallInt;XRadius:  Word;
                                                   YRadius:  Word)

    Visibility:   default

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 (602  ), Circle (599  ), GetArcCoords (605  ), PieSlice (614  ), Sector (615  )
                12.13.10           FillPoly

    Synopsis:    Draw, close and fill a polygone

Declaration:     procedure  FillPoly(NumPoints:  Word;var  PolyPoints)

    Visibility:   default

Description:     FillPoly 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 (602  ), Bar3D (602  ), Rectangle (614  )
                12.13.11           FloodFill

    Synopsis:    Fill an area with a given color

Declaration:     procedure  FloodFill(x:  SmallInt;y:  SmallInt;Border:  Word)

    Visibility:   default

Description:     Fills the area containing the point (X,Y), bounded by the color BorderColor.

       Errors:   None

    See also:    SetColor (616  ), SetBkColor (616  )



                                                                                 604

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.12           GetArcCoords

    Synopsis:    Return coordinates of last drawn arc or ellipse.

Declaration:     procedure  GetArcCoords(var  ArcCoords:  ArcCoordsType)

    Visibility:   default

Description:     GetArcCoords returns the coordinates of the latest Arc or Ellipse call.

       Errors:   None.

    See also:    Arc (602  ), Ellipse (604  )
                12.13.13           GetAspectRatio

    Synopsis:    Return screen resolution

Declaration:     procedure  GetAspectRatio(var  Xasp:  Word;var  Yasp:  Word)

    Visibility:   default

Description:     GetAspectRatio  determines  the  effective  resolution  of  the  screen.  The  aspect  ration  can
                then be calculated as Xasp/Yasp.

       Errors:   None.

    See also:    InitGraph (611  ), SetAspectRatio (616  )
                12.13.14           GetBkColor

    Synopsis:    Return current background color

Declaration:     function  GetBkColor  :  Word

    Visibility:   default

Description:     GetBkColor returns the current background color (the palette entry).

       Errors:   None.

    See also:    GetColor (605  ), SetBkColor (616  )
                12.13.15           GetColor

    Synopsis:    Return current drawing color

Declaration:     function  GetColor  :  Word

    Visibility:   default

Description:     GetColor returns the current drawing color (the palette entry).

       Errors:   None.

    See also:    GetColor (605  ), SetBkColor (616  )


                                                                                 605

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.16           GetDefaultPalette

    Synopsis:    Return default palette

Declaration:     procedure  GetDefaultPalette(var  Palette:  PaletteType)

    Visibility:   default

Description:     GetDefaultPalette returns the current palette in Palette.

       Errors:   None.

    See also:    GetColor (605  ), GetBkColor (605  )
                12.13.17           GetDirectVideo

    Synopsis:    Determine whether direct video mode is active.

Declaration:     function  GetDirectVideo  :  Boolean

    Visibility:   default

Description:     Determine whether direct video mode is active.

       Errors:
                12.13.18           GetDriverName

    Synopsis:    Return current driver name

Declaration:     function  GetDriverName  :  String

    Visibility:   default

Description:     GetDriverName returns a string containing the name of the current driver.

       Errors:   None.

    See also:    GetModeName (608  ), InitGraph (611  )
                12.13.19           GetFillPattern

    Synopsis:    Return current fill pattern

Declaration:     procedure  GetFillPattern(var  FillPattern:  FillPatternType)

    Visibility:   default

Description:     GetFillPattern returns an array with the current fill-pattern in FillPattern

       Errors:   None

    See also:    SetFillPattern (617  )


                                                                                 606

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.20           GetFillSettings

    Synopsis:    Return current fill settings

Declaration:     procedure  GetFillSettings(var  Fillinfo:  FillSettingsType)

    Visibility:   default

Description:     GetFillSettings returns the current fill-settings in FillInfo

       Errors:   None.

    See also:    SetFillPattern (617  )
                12.13.21           GetGraphMode

    Synopsis:    Get current graphical modus

Declaration:     function  GetGraphMode  :  SmallInt

    Visibility:   default

Description:     GetGraphMode returns the current graphical modus

       Errors:   None.

    See also:    InitGraph (611  )
                12.13.22           GetLineSettings

    Synopsis:    Get current line drawing settings

Declaration:     procedure  GetLineSettings(var  ActiveLineInfo:  LineSettingsType)

    Visibility:   default

Description:     GetLineSettings returns the current Line settings in LineInfo

       Errors:   None.

    See also:    SetLineStyle (618  )
                12.13.23           GetMaxColor

    Synopsis:    return maximum number of colors

Declaration:     function  GetMaxColor  :  Word

    Visibility:   default

Description:     GetMaxColor returns the maximum color-number which can be set with SetColor.  Contrary
                to Turbo Pascal, this color isn't always guaranteed to be white (for instance in 256+ color
                modes).

       Errors:   None.

    See also:    SetColor (616  ), GetPaletteSize (609  )
                                                                                 607

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.24           GetMaxMode

    Synopsis:    Return biggest mode for the current driver

Declaration:     function  GetMaxMode  :  SmallInt

    Visibility:   default

Description:     GetMaxMode returns the highest modus for the current driver.

       Errors:   None.

    See also:    InitGraph (611  )
                12.13.25           GetMaxX

    Synopsis:    Return maximal X coordinate

Declaration:     function  GetMaxX  :  SmallInt

    Visibility:   default

Description:     GetMaxX returns the maximum horizontal screen length

       Errors:   None.

    See also:    GetMaxY (608  )
                12.13.26           GetMaxY

    Synopsis:    Return maximal Y coordinate

Declaration:     function  GetMaxY  :  SmallInt

    Visibility:   default

Description:     GetMaxY returns the maximum number of screen lines

       Errors:   None.

    See also:    GetMaxY (608  )
                12.13.27           GetModeName

    Synopsis:    Return description a modus

Declaration:     function  GetModeName(ModeNumber:  SmallInt)  :  String

    Visibility:   default

Description:     GetModeName Returns a string with the name of modus Modus

       Errors:   None.

    See also:    GetDriverName (606  ), InitGraph (611  )



                                                                                 608

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.28           GetModeRange

    Synopsis:    Return lowest and highest modus of current driver

Declaration:     procedure  GetModeRange(GraphDriver:  SmallInt;var  LoMode:  SmallInt;
                                                     var  HiMode:  SmallInt)

    Visibility:   default

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 (611  )
                12.13.29           GetPalette

    Synopsis:    Return current palette

Declaration:     procedure  GetPalette(var  Palette:  PaletteType)

    Visibility:   default

Description:     GetPalette returns in Palette the current palette.

       Errors:   None.

    See also:    GetPaletteSize (609  ), SetPalette (618  )
                12.13.30           GetPaletteSize

    Synopsis:    Return maximal number of entries in current palette

Declaration:     function  GetPaletteSize  :  SmallInt

    Visibility:   default

Description:     GetPaletteSize returns the maximum number of entries in the current palette.

       Errors:   None.

    See also:    GetPalette (609  ), SetPalette (618  )
                12.13.31           GetTextSettings

    Synopsis:    Return current text style

Declaration:     procedure  GetTextSettings(var  TextInfo:  TextSettingsType)

    Visibility:   default

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 (619  ), SetTextJustify (618  )


                                                                                 609

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.32           GetViewSettings

    Synopsis:    Return current viewport

Declaration:     procedure  GetViewSettings(var  viewport:  ViewPortType)

    Visibility:   default

Description:     GetViewSettings returns the current viewport and clipping settings in ViewPort.

       Errors:   None.

    See also:    SetViewPort (620  )
                12.13.33           GetX

    Synopsis:    Return current cursor X position

Declaration:     function  GetX  :  SmallInt

    Visibility:   default

Description:     GetX returns the X-coordinate of the current position of the graphical pointer

       Errors:   None.

    See also:    GetY (610  )
                12.13.34           GetY

    Synopsis:    Return current cursor Y position

Declaration:     function  GetY  :  SmallInt

    Visibility:   default

Description:     GetY returns the Y-coordinate of the current position of the graphical pointer

       Errors:   None.

    See also:    GetX (610  )
                12.13.35           GraphDefaults

    Synopsis:    Reset graphical mode to defaults

Declaration:     procedure  GraphDefaults

    Visibility:   default

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 (620  ), SetFillStyle (617  ), SetColor (616  ), SetBkColor (616  ), SetLineStyle (618  )
                                                                                 610

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.36           GraphErrorMsg

    Synopsis:    Return a description of an error

Declaration:     function  GraphErrorMsg(ErrorCode:  SmallInt)  :  String

    Visibility:   default

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 (611  )
                12.13.37           GraphResult

    Synopsis:    Result of last graphical operation

Declaration:     function  GraphResult  :  SmallInt

    Visibility:   default

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 (612  )

                      oSetLineStyle (618  )

                      oSetWriteMode (620  )

                      oSetFillStyle (617  )

                      oSetTextJustify (618  )

                      oSetGraphMode (617  )

                      oSetTextStyle (619  )


       Errors:   None.

    See also:    GraphErrorMsg (611  )
                12.13.38           InitGraph

    Synopsis:    Initialize grpahical system

Declaration:     procedure  InitGraph(var  GraphDriver:  SmallInt;var  GraphMode:  SmallInt;
                                                const  PathToDriver:  String)

    Visibility:   default

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 Bor-
                land.  Free Pascal does not offer BGI fonts like Borland, these must be obtained separately.

                Example code:



                                                                                 611

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                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.


       Errors:   None.

    See also:    Modes (577  ), DetectGraph (603  ), CloseGraph (603  ), GraphResult (611  )
                12.13.39           InstallUserDriver

    Synopsis:    Install a user driver

Declaration:     function  InstallUserDriver(Name:  String;AutoDetectPtr:  Pointer)
                                                             :  SmallInt

    Visibility:   default

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 (611  ), InstallUserFont (612  )
                12.13.40           InstallUserFont

    Synopsis:    Install a user-defined font

Declaration:     function  InstallUserFont(const  FontFileName:  String)  :  SmallInt

    Visibility:   default

Description:     InstallUserFont adds the font in FontPath to the list of fonts of the .BGI system.

       Errors:   None.

    See also:    InitGraph (611  ), InstallUserDriver (612  )
                12.13.41           LineRel

    Synopsis:    Draw a line starting from current position in given direction

Declaration:     procedure  LineRel(Dx:  SmallInt;Dy:  SmallInt)

    Visibility:   default


                                                                                 612

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
Description:     LineRel  draws  a  line  starting  from  the  current  pointer  position  to  the  point(DX,DY),
                \textbf{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 (600  ), LineTo (613  )
                12.13.42           LineTo

    Synopsis:    Draw a line starting from current position to a given point

Declaration:     procedure  LineTo(X:  SmallInt;Y:  SmallInt)

    Visibility:   default

Description:     LineTo draws a line starting from the current pointer position to the point(DX,DY, \textbf{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 (612  ), Line (600  )
                12.13.43           MoveRel

    Synopsis:    Move cursor relative to current position

Declaration:     procedure  MoveRel(Dx:  SmallInt;Dy:  SmallInt)

    Visibility:   default

Description:     MoveRel moves the pointer to the point (DX,DY), relative to the current pointer position

       Errors:   None.

    See also:    MoveTo (613  )
                12.13.44           MoveTo

    Synopsis:    Move cursor to absolute position.

Declaration:     procedure  MoveTo(X:  SmallInt;Y:  SmallInt)

    Visibility:   default

Description:     MoveTo moves the pointer to the point (X,Y).

       Errors:   None.

    See also:    MoveRel (613  )
                                                                                 613

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.45           OutText

    Synopsis:    Write text on the screen at the current location.

Declaration:     procedure  OutText(const  TextString:  String)

    Visibility:   default

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 (600  )
                12.13.46           PieSlice

    Synopsis:    Draw a pie-slice

Declaration:     procedure  PieSlice(X:  SmallInt;Y:  SmallInt;stangle:  SmallInt;
                                              endAngle:  SmallInt;Radius:  Word)

    Visibility:   default

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 (602  ), Circle (599  ), Sector (615  )
                12.13.47           queryadapterinfo

    Synopsis:    Function called to retrieve the current video adapter settings.

Declaration:     function  queryadapterinfo  :  PModeInfo

    Visibility:   default
                12.13.48           Rectangle

    Synopsis:    Draw a rectangle on the screen.

Declaration:     procedure  Rectangle(x1:  SmallInt;y1:  SmallInt;x2:  SmallInt;y2:  SmallInt)

    Visibility:   default

Description:     Draws a rectangle with corners at (X1,Y1) and (X2,Y2), using the current color and style.

       Errors:   None.

    See also:    Bar (602  ), Bar3D (602  )



                                                                                 614

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.49           RegisterBGIDriver

    Synopsis:    Register a new BGI driver.

Declaration:     function  RegisterBGIDriver(driver:  pointer)  :  SmallInt

    Visibility:   default

Description:     Registers a user-defined BGI driver

       Errors:   None.

    See also:    InstallUserDriver (612  ), RegisterBGIFont (615  )
                12.13.50           RegisterBGIfont

    Synopsis:    Register a new BGI font

Declaration:     function  RegisterBGIfont(font:  pointer)  :  SmallInt

    Visibility:   default

Description:     Registers a user-defined BGI driver

       Errors:   None.

    See also:    InstallUserFont (612  ), RegisterBGIDriver (615  )
                12.13.51           RestoreCrtMode

    Synopsis:    Restore text screen

Declaration:     procedure  RestoreCrtMode

    Visibility:   default

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 (611  )
                12.13.52           Sector

    Synopsis:    Draw and fill a sector of an ellipse

Declaration:     procedure  Sector(x:  SmallInt;y:  SmallInt;StAngle:  Word;EndAngle:  Word;
                                           XRadius:  Word;YRadius:  Word)

    Visibility:   default

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 (602  ), Circle (599  ), PieSlice (614  )

                                                                                 615

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.53           SetAspectRatio

    Synopsis:    Set aspect ration of the screen

Declaration:     procedure  SetAspectRatio(Xasp:  Word;Yasp:  Word)

    Visibility:   default

Description:     Sets the aspect ratio of the current screen to Xasp/Yasp.

       Errors:   None

    See also:    InitGraph (611  ), GetAspectRatio (605  )
                12.13.54           SetBkColor

    Synopsis:    Set background drawing color

Declaration:     procedure  SetBkColor(ColorNum:  Word)

    Visibility:   default

Description:     Sets the background color to Color.

       Errors:   None.

    See also:    GetBkColor (605  ), SetColor (616  ), SetWriteMode (620  )
                12.13.55           SetColor

    Synopsis:    Set foreground drawing color

Declaration:     procedure  SetColor(Color:  Word)

    Visibility:   default

Description:     Sets the foreground color to Color.

       Errors:   None.

    See also:    GetColor (605  ), SetBkColor (616  ), SetWriteMode (620  )
                12.13.56           SetDirectVideo

    Synopsis:    Attempt to enter direct video mode.

Declaration:     procedure  SetDirectVideo(DirectAccess:  Boolean)

    Visibility:   default

Description:     SetDirectVideo attempts to enter direct video mode.  In that mode, everything is drawn
                straight in the video buffer.



                                                                                 616

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.57           SetFillPattern

    Synopsis:    Set drawing fill pattern

Declaration:     procedure  SetFillPattern(Pattern:  FillPatternType;Color:  Word)

    Visibility:   default

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 (606  ), SetFillStyle (617  ), SetWriteMode (620  )
                12.13.58           SetFillStyle

    Synopsis:    Set drawing fill style

Declaration:     procedure  SetFillStyle(Pattern:  Word;Color:  Word)

    Visibility:   default

Description:     SetFillStyle  sets  the  filling  pattern  and  color  to  one  of  the  predefined  filling  patterns.
                Pattern can be one of the following predefined constants :

                EmptyFill       Uses backgroundcolor.

                SolidFill    Uses filling color

                LineFill    Fills with horizontal lines.

                ltSlashFill     Fills with lines from left-under to top-right.

                SlashFill     Idem as previous, thick lines.

                BkSlashFill       Fills with thick lines from left-Top to bottom-right.

                LtBkSlashFill         Idem as previous, normal lines.

                HatchFill      Fills with a hatch-like pattern.

                XHatchFill        Fills with a hatch pattern, rotated 45 degrees.

                InterLeaveFill

                WideDotFill         Fills with dots, wide spacing.

                CloseDotFill        Fills with dots, narrow spacing.

                UserFill     Fills with a user-defined pattern.

       Errors:   None.

    See also:    SetFillPattern (617  ), SetWriteMode (620  )
                12.13.59           SetGraphMode

    Synopsis:    Set graphical mode

Declaration:     procedure  SetGraphMode(Mode:  SmallInt)

    Visibility:   default

Description:     SetGraphMode sets the graphical mode and clears the screen.

       Errors:   None.

    See also:    InitGraph (611  )



                                                                                 617

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.60           SetLineStyle

    Synopsis:    Set line drawing style

Declaration:     procedure  SetLineStyle(LineStyle:  Word;Pattern:  Word;Thickness:  Word)

    Visibility:   default

Description:     SetLineStyle sets the drawing style for lines.  You can specify a LineStyle which is one
                of the following pre-defined constants:


                Solidln    draws a solid line.

                Dottedln      Draws a dotted line.

                Centerln      draws a non-broken centered line.

                Dashedln       draws a dashed line.

                UserBitln       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:


                NormWidth           Normal line width

                ThickWidth         Double line width


       Errors:   None.

    See also:    GetLineSettings (607  ), SetWriteMode (620  )
                12.13.61           SetPalette

    Synopsis:    Set palette entry using color constant

Declaration:     procedure  SetPalette(ColorNum:  Word;Color:  ShortInt)

    Visibility:   default

Description:     SetPalette changes the ColorNr-th entry in the palette to NewColor

       Errors:   None.

    See also:    SetAllPalette (601  ), SetRGBPalette (601  )
                12.13.62           SetTextJustify

    Synopsis:    Set text placement style

Declaration:     procedure  SetTextJustify(horiz:  Word;vert:  Word)

    Visibility:   default

Description:     SetTextJustify controls the placement of new text, relative to the (graphical) cursor posi-
                tion.  Horizontal controls horizontal placement, and can be one of the following pre-defined
                constants:


                LeftText      Text is set left of the pointer.

                CenterText        Text is set centered horizontally on the pointer.
                                                                                 618

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                RightText       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 :


                BottomText         Text is placed under the pointer.

                CenterText       Text is placed centered vertically on the pointer.

                TopText      Text is placed above the pointer.


       Errors:   None.

    See also:    OutText (614  ), OutTextXY (600  )
                12.13.63           SetTextStyle

    Synopsis:    Set text style

Declaration:     procedure  SetTextStyle(font:  Word;direction:  Word;charsize:  Word)

    Visibility:   default

Description:     SetTextStyle controls the style of text to be put on the screen.  pre-defined constants for
                Font are:


                DefaultFont        The default font

                TriplexFont        A special font

                SmallFont       A smaller font

                SansSerifFont         A sans-serif font (like Arial)

                GothicFont        A gothic font

                ScriptFont       A script font

                SimpleFont        A simple font

                TSCRFont         Terminal screen font

                LCOMFont          ?

                EuroFont       ?

                BoldFont       A bold typeface font


                Pre-defined constants for Direction are :


                HorizDir      Write horizontal

                VertDir     Write vertical


       Errors:   None.

    See also:    GetTextSettings (609  )

                                                                                 619

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.64           SetUserCharSize

    Synopsis:    Set user character size for vector font

Declaration:     procedure  SetUserCharSize(Multx:  Word;Divx:  Word;Multy:  Word;Divy:  Word)

    Visibility:   default

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 (619  )
                12.13.65           SetViewPort

    Synopsis:    Set the graphical drawing window

Declaration:     procedure  SetViewPort(X1:  SmallInt;Y1:  SmallInt;X2:  SmallInt;
                                                   Y2:  SmallInt;Clip:  Boolean)

    Visibility:   default

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 (610  )
                12.13.66           SetWriteMode

    Synopsis:    Specify binary operation to perform when drawing on screen

Declaration:     procedure  SetWriteMode(WriteMode:  SmallInt)

    Visibility:   default

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:


                CopyPut       Draw as specified using current bitmask and color

                XORPut        Draw XOR-ing current bitmask and color


       Errors:   None.

    See also:    SetColor (616  ), SetBkColor (616  ), SetLineStyle (618  ), SetFillStyle (617  )

                                                                                 620

                ___________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________
                12.13.67           TextHeight

    Synopsis:    Return height (in pixels) of the given string

Declaration:     function  TextHeight(const  TextString:  String)  :  Word

    Visibility:   default

Description:     TextHeight returns the height (in pixels) of the string S in the current font and text-size.

       Errors:   None.

    See also:    TextWidth (621  )
                12.13.68           TextWidth

    Synopsis:    Return width (in pixels) of the given string

Declaration:     function  TextWidth(const  TextString:  String)  :  Word

    Visibility:   default

Description:     TextHeight returns the width (in pixels) of the string S in the current font and text-size.

       Errors:   None.

    See also:    TextHeight (621  )
                                                                                 621


Chapter   13


Reference   for   unit   'heaptrc'
13.1          Controlling  HeapTrc  with  environment  variables


The HeapTrc unit can be controlled with the HEAPTRC environment variable.  The contents
of this variable controls the initial setting of some constants in the unit.  HEAPTRC consists of
one or more of the following strings, separated by spaces:


keepreleased          If this string occurs, then the KeepReleased (624  ) variable is set to True

disabled       If this string occurs, then the UseHeapTrace (624  ) variable is set to False and the
        heap trace is disabled.  It does not make sense to combine this value with other values.

nohalt      If  this  string  occurs,  then  the  HaltOnError  (623  )  variable  is  set  to  False,  so  the
        program continues executing even in case of a heap error.

log=filename          If  this  string  occurs,  then  the  output  of  heaptrc  is  sent  to  the  specified
        Filename.  (see also SetHeapTraceOutput (626  ))


The following are valid values for the HEAPTRC variable:


HEAPTRC=disabled
HEAPTRC="keepreleased  log=heap.log"
HEAPTRC="log=myheap.log  nohalt"


Note that these strings are case sensitive, and the name of the variable too.
13.2          HeapTrc  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 below example shows how to use the heaptrc unit.

This is the memory dump shown when running this program in a standard way:
                                                             622

_______________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________________________*
 *___
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.
13.3          Overview


This  document  describes  the  HEAPTRC  unit  for  Free  Pascal.   It  was  written  by  Pierre
Muller.  It is system independent, and works on all supported systems.

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.
13.4          Constants,  types  and  variables



13.4.1         Constants

add_tail  :  Boolean  =  true


If  add\_tail is True (the default) then a check is also performed on the memory location
just behind the allocated memory.


HaltOnError  :  Boolean  =  true


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.



                                                                 623

_______________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________________________*
 *___
HaltOnNotReleased  :  Boolean  =  false


HaltOnNotReleased can be set to True to make the DumpHeap (625  ) procedure halt (exit
code  203)  the  program  if  any  memory  was  not  released  when  the  dump  is  made.   If  it  is
False (the default) then DumpHeap just returns.


keepreleased  :  Boolean  =  false


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.


quicktrace  :  Boolean  =  true


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 True.


tracesize  =  8


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.


usecrc  :  Boolean  =  true


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.


useheaptrace  :  Boolean  =  true


This variable must be set at program startup, through the help of an environment variable.
13.4.2         Types

tdisplayextrainfoProc  =  procedure(var  ptext:  text;p:  pointer)


The TDisplayExtraInfoType is a procedural type used in the SetHeapExtraInfo (625  ) call
to display a memory location which was previously filled with TFillExtraInfoProc (624  )


tFillExtraInfoProc  =  procedure(p:  pointer)


The TFillExtraInfoProc is a procedural type used in the SetHeapExtraInfo (625  ) call to
fill a memory location with extra data for displaying.
                                                                 624

                _______________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________
                13.5          Procedures  and  functions



                13.5.1         DumpHeap

    Synopsis:    Dump memory usage report to stderr.

Declaration:     procedure  DumpHeap

    Visibility:   default

Description:     DumpHeap dumps to standard output a summary of memory usage.  It is called automatically
                by the heaptrc unit when your program exits (by installing an exit procedure), but it can be
                called at any time.

       Errors:   None.

    See also:    MarkHeap (622  )
                13.5.2         SetHeapExtraInfo

    Synopsis:    Store extra information in blocks.

Declaration:     procedure  SetHeapExtraInfo(size:  ptrint;fillproc:  tFillExtraInfoProc;
                                                           displayproc:  tdisplayextrainfoProc)

    Visibility:   default

Description:     You  can  use  SetHeapExtraInfo  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 mech-
                anism should reserve for your extra information.  For each call to getmem, FillProc will be
                called, and passed a pointer to the memory reserved.

                When dumping the memory summary, the extra info is shown by calling displayproc and
                passing it the memory location which was filled by fillproc.  It should write the information
                in readable form to the text file provided in the call to displayproc

       Errors:   You can only call SetHeapExtraInfo if no memroy has been allocated yet.  If memory was
                already allocated prior to the call to SetHeapExtraInfo, then an error will be displayed on
                standard error output, and a DumpHeap (625  ) is executed.

    See also:    DumpHeap (625  ), SetHeapTraceOutput (626  )


                Listing:  ./heapex/setinfo.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       h e a p e x;


                {   Program       u s e d  t o  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;
                       M a r k e r  :  L o n g i n t;


                 P r o c e d u r eS 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;

                                                                                 625

                _______________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________
                 b e g i n
                    P L o n g i n t(P) ^ : =M a r k e r;
                end   ;


                 P r o c e d u r e  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       w i t h $FFAAFFAA        =  -5570646
                    M a r k e r : =  $FFAAFFAA       ;
                    New  ( P1  ) ;
                    New  ( P1  ) ;
                    D i s p o s e(P1  ) ;
                    For    I : = 1  t o  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   ;


                 P r o c e d u r e  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       w i t h $FAFAFAFA        =  -84215046
                    M a r k e r : =  $FAFAFAFA       ;
                    New  ( P1  ) ;
                    New  ( P1  ) ;
                    D i s p o s e(P1  ) ;
                    For    I : = 1  t o  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(M a r k e r) ,@ S e t M a r k e r) ;
                  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___.____________________________________________________________________________________________________________*
 *___________

                13.5.3         SetHeapTraceOutput

    Synopsis:    Specify filename for heap trace output.

Declaration:     procedure  SetHeapTraceOutput(const  name:  String)

    Visibility:   default

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.
                                                                                 626

            _______________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'HEAPTRC'______________________*
 *_______________
See also:    SetHeapExtraInfo (625  )



                                                                             627


Chapter   14


Reference   for   unit   'ipc'
14.1          Used  units
                                       Table 14.1:  Used units by unit 'ipc'


                                                 __Name______________Page____
                                                   BaseUnix           628
                                                   UnixType           628



14.2          Overview


This document describes the IPC unit for Free Pascal.  It was written for linux by Michael
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.

Many constants here are provided for completeness only, and should under normal circum-
stances not be used by the programmer.
14.3          Constants,  types  and  variables



14.3.1         Constants

IPC_CREAT  =  1  shl  9


Create if key is nonexistent


IPC_EXCL  =  2  shl  9


fail if key exists


IPC_INFO  =  3


For ipcs call
                                                             628

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
IPC_NOWAIT  =  4  shl  9


return error on wait


IPC_RMID  =  0


Remove resource


IPC_SET  =  1


set ipc_perm options


IPC_STAT  =  2


get ipc_perm options


MSGMAX  =  4056


Internal Message control code.  Do not use


MSGMNB  =  16384


Internal Message control code.  Do not use


MSGMNI  =  128


Internal Message control code.  Do not use


MSG_EXCEPT  =  2  shl  12


Internal Message control code.  Do not use


MSG_NOERROR  =  1  shl  12


Internal Message control code.  Do not use


SEM_GETALL  =  13


Semaphore operation:  Get all semaphore values


SEM_GETNCNT  =  14


Semaphore operation:  Get number of processes waiting for resource.


SEM_GETPID  =  11


Semaphore operation:  Get process ID of last operation.


SEM_GETVAL  =  12


Semaphore operation:  Get current value of semaphore



                                                                 629

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
SEM_GETZCNT  =  15


Semaphore operation:  Get number of processes waiting for semaphores to reach zero


SEM_SEMMNI  =  128


Semaphore operation:  ?


SEM_SEMMNS  =  (SEM_SEMMNI  *  SEM_SEMMSL  )


Semaphore operation:  ?


SEM_SEMMSL  =  32


Semaphore operation:  ?


SEM_SEMOPM  =  32


Semaphore operation:  ?


SEM_SEMVMX  =  32767


Semaphore operation:  ?


SEM_SETALL  =  17


Semaphore operation:  Set all semaphore values


SEM_SETVAL  =  16


Semaphore operation:  Set semaphore value


SEM_UNDO  =  $1000


Constant for use in semop (644  )


SHM_LOCK  =  11


This constant is used in the shmctl (646  ) call.


SHM_R  =  4  shl  6


This constant is used in the shmctl (646  ) call.


SHM_RDONLY  =  1  shl  12


This constant is used in the shmctl (646  ) call.


SHM_REMAP  =  4  shl  12


This constant is used in the shmctl (646  ) call.



                                                                 630

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
SHM_RND  =  2  shl  12


This constant is used in the shmctl (646  ) call.


SHM_UNLOCK  =  12


This constant is used in the shmctl (646  ) call.


SHM_W  =  2  shl  6


This constant is used in the shmctl (646  ) call.
14.3.2         Types

key_t  =  TKey


Alias for TKey (632  ) type


msglen_t  =  culong


Message length type


msgqnum_t  =  culong


Message queue number type


PIPC_Perm  =  ^TIPC_Perm


Pointer to TIPC_Perm (632  ) record.


PMSG  =  ^TMSG


Pointer to TMSG (632  ) record


PMSGbuf  =  ^TMSGbuf


Pointer to TMsgBuf (633  ) rcord


PMSGinfo  =  ^TMSGinfo


Pointer to TMSGinfo (633  ) record


PMSQid_ds  =  ^TMSQid_ds


Pointer to TMSQid_ds (633  )


PSEMbuf  =  ^TSEMbuf


Pointer to TSembuf (633  ) record.
                                                                 631

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
PSEMid_ds  =  ^TSEMid_ds


Pointer to TSEMid_ds (634  ) record.


PSEMinfo  =  ^TSEMinfo


Pointer to TSEMinfo (634  ) record.


PSEMun  =  ^TSEMun


Pointer to TSEMun (634  ) record


PShmid_DS  =  ^TShmid_ds


Pointer to TSHMid_ds (634  ) record.


PSHMinfo  =  ^TSHMinfo



TIPC_Perm  =  record
   key  :  TKey;
   uid  :  uid_t;
   gid  :  gid_t;
   cuid  :  uid_t;
   cgid  :  gid_t;
   mode  :  mode_t;
   seq  :  cushort;
end
TIPC_Perm  is  used  in  all  IPC  systems  to  specify  the  permissions.  It  should  never  be  used
directly.


TKey  =  cint


Type returned by the ftok (635  ) key generating function.


TMSG  =  record
   msg_next  :  PMSG;
   msg_type  :  LongInt;
   msg_spot  :  PChar;
   msg_stime  :  LongInt;
   msg_ts  :  Integer;
end
Record used in the handling of message queues.  Do not use directly.


TMSGbuf  =  record
   mtype  :  clong;
   mtext  :  Array[0..0]  of  Char;
end

                                                                 632

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
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.


TMSGinfo  =  record
   msgpool  :  cint;
   msgmap  :  cint;
   msgmax  :  cint;
   msgmnb  :  cint;
   msgmni  :  cint;
   msgssz  :  cint;
   msgtql  :  cint;
   msgseg  :  cushort;
end
Internal message system record.  Do not use directly.


TMSQid_ds  =  record
   msg_perm  :  TIPC_Perm;
   msg_first  :  PMSG;
   msg_last  :  PMSG;
   msg_stime  :  time_t;
   msg_rtime  :  time_t;
   msg_ctime  :  time_t;
   msg_cbytes  :  Word;
   msg_qnum  :  Word;
   msg_qbytes  :  Word;
   msg_lspid  :  ipc_pid_t;
   msg_lrpid  :  ipc_pid_t;
end
This  record  should  never  be  used  directly,  it  is  an  internal  kernel  record.   It's  fields  may
change at any time.


TSEMbuf  =  record
   sem_num  :  cushort;
   sem_op  :  cshort;
   sem_flg  :  cshort;
end
The TSEMbuf record is used in the semop (644  ) call, and is used to specify which operations
you want to do.


TSEMid_ds  =  record
   sem_perm  :  TIPC_Perm;
   sem_otime  :  time_t;
   sem_ctime  :  time_t;
   sem_base  :  pointer;
   sem_pending  :  pointer;



                                                                 633

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
   sem_pending_last  :  pointer;
   undo  :  pointer;
   sem_nsems  :  cushort;
end
Structure returned by the semctl (639  ) call, contains all data of a semahore


TSEMinfo  =  record
   semmap  :  cint;
   semmni  :  cint;
   semmns  :  cint;
   semmnu  :  cint;
   semmsl  :  cint;
   semopm  :  cint;
   semume  :  cint;
   semusz  :  cint;
   semvmx  :  cint;
   semaem  :  cint;
end
Internal semaphore system record.  Do not use.


TSEMun  =  record
end
Record used in semctl (639  ) call.


TShmid_ds  =  record
   shm_perm  :  TIPC_Perm;
   shm_segsz  :  cint;
   shm_atime  :  time_t;
   shm_dtime  :  time_t;
   shm_ctime  :  time_t;
   shm_cpid  :  ipc_pid_t;
   shm_lpid  :  ipc_pid_t;
   shm_nattch  :  Word;
   shm_npages  :  Word;
   shm_pages  :  Pointer;
   attaches  :  pointer;
end
Record used in the shmctl (646  ) call to set or retrieve settings for shared memory.


TSHMinfo  =  record
   shmmax  :  cint;
   shmmin  :  cint;
   shmmni  :  cint;
   shmseg  :  cint;
   shmall  :  cint;
end

                                                                 634

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
                Record used by the shared memory system, Do not use directly.
                14.4          Procedures  and  functions



                14.4.1         ftok

    Synopsis:    Create token from filename

Declaration:     function  ftok(Path:  pchar;ID:  cint)  :  TKey

    Visibility:   default

Description:     ftok returns a key that can be used in a semget (644  )shmget (648  ) or msgget (638  ) 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

                For an example, see msgctl (635  ), semctl (639  ) or shmctl (646  ).

       Errors:   ftok returns -1 if the file in Path doesn't exist.

    See also:    semget (644  ), shmget (648  ), msgget (638  )
                14.4.2         msgctl

    Synopsis:    Perform various operations on a message queue

Declaration:     function  msgctl(msqid:  cint;cmd:  cint;buf:  PMSQid_ds)  :  cint

    Visibility:   default

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 (638  ), msgsnd (639  ), msgrcv (638  )


                Listing:  ./ipcex/msgtool.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program        m s g t o o l;


                Uses     i p c ,b a s e u n i x;


                Type



                                                                                 635

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
    PMyMsgBuf        =  ^ TMyMsgBuf        ;
    TMyMsgBuf        =   r e c o r d
       mtype      :   L o n g i n t;
        m t e x t :   s t r i n g[ 2 5 5 ] ;
    end  ;


 P r o c e d u r eD 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  :  ' , f p g e t e r r n)o;
    h a l t( 1 ) ;
end   ;


 P r o c e d u r eS e n d M e s s a g e( 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 m e s s a g e. ') ;
    Buf  . mtype    := mtype    ;
    Buf  . Mtext    := m t e x t;
    I f    msgsnd    ( I d ,PMsgBuf      (@Buf   ) , 2 5 6 , 0 ) = - 1then
        D o E r r o r('msgsnd     ' ) ;
end   ;


 P r o c e d u r eReadMessage          ( 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 m e s s a g e. ') ;
    Buf  . MType    := MType    ;
    I f  m s g r c v(ID  ,PMSGBuf      (@Buf    ) , 2 5 6 ,mtype   ,0)<>-1       then
        W r i t e l n(  'Type     :  ' , b u f.mtype    , '   T e x t :   ' ,b u f .m t e x t)
    e l s e
        D o E r r o r(  'm s g r c v') ;
end   ;


 P r o c e d u r eRemoveQueue          (  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)<>-1      then
        W r i t e l n(  'Removed       Queue     w i t h  i d   ', I d) ;
end   ;


 P r o c e d u r eChangeQueueMode             (ID  , mode     :  l o n g i n t) ;


Var    QueueDS        :  TMSQid _ds      ;


 b e g i n
    I f    m s g c t l ( I d ,IPC _STAT     , @QueueDS      )=-1    then
        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      )=0    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
                                                                 636

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
      D o E r r o r ( 'm s g c t l  :  IPC _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 5  c h a r a c t e r)s' ) ;
    W r i t e l n ( '                            r ( e c e i v e)  < t 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 m a l mode   > ' ) ;
    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       ;


 c o n s t i p c k e y =   ' . '#0;


 b e g i n
    I f  Paramcount        <1   then     Usage    ;
    k e y  : =F t o k( @ i p c k e y[ 1 ] ,o r d( 'M ' ) ) ;
    ID :=  m s g g e t(key   ,IPC_CREAT         o r  4 3 8 ) ;
    I f  ID  <0   then     D o E r r o r(  'MsgGet     ' ) ;
    Case     upCase    ( Paramstr      ( 1 ) [ 1 ] ) o f
      'S  '  :  I f  ParamCount        <>3    then
                    Usage
                e l s e
                    S e n d M e s s a g e(i d ,Buf   , S t r T o I n t(Paramstr     ( 2 ) ) ,p a r a m s t r( 3 ) ) ;
      '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(r2 ) ) ) ;
      e l s e
         Usage
      end  ;
end___._______________________________________________________________________________________________________________________


                                                                 637

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
                14.4.3         msgget

    Synopsis:    Return message queue ID, possibly creating the queue

Declaration:     function  msgget(key:  TKey;msgflg:  cint)  :  cint

    Visibility:   default

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.

                For an example, see msgctl (635  ).

       Errors:   On error, -1 is returned, and IPCError is set.

    See also:    ftok (635  ), msgsnd (639  ), msgrcv (638  ), msgctl (635  )
                14.4.4         msgrcv

    Synopsis:    Retrieve a message from the queue

Declaration:     function  msgrcv(msqid:  cint;msgp:  PMSGbuf;msgsz:  size_t;msgtyp:  cint;
                                         msgflg:  cint)  :  cint

    Visibility:   default

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:


                0 No 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.

                For an example, see msgctl (635  ).

       Errors:   In case of error, False is returned, and IPCerror is set.

    See also:    msgget (638  ), msgsnd (639  ), msgctl (635  )



                                                                                 638

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
                14.4.5         msgsnd

    Synopsis:    Send a message to the messague queue

Declaration:     function  msgsnd(msqid:  cint;msgp:  PMSGbuf;msgsz:  size_t;msgflg:  cint)
                                           :  cint

    Visibility:   default

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):


                0 No 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.

                For an example, see msgctl (635  ).

       Errors:   In case of error, the call returns False, and IPCerror is set.

    See also:    msgget (638  ), msgrcv (638  ), msgctl (635  )
                14.4.6         semctl

    Synopsis:    Perform various control operations on a semaphore set

Declaration:     function  semctl(semid:  cint;semnum:  cint;cmd:  cint;var  arg:  TSEMun)
                                           :  cint

    Visibility:   default

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.
                                                                                 639

            _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'________________*
 *_______________
            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 \var{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 number of processes waiting
                  for resources.

            GETPID        semctl returns the process ID of the process that performed the last semop (644  )
                  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
                  \var{SizeOf(Word)*  Number  of  semaphores  in  the  set}.   This  call  will  then  set  the
                  values 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 (644  ), semop (644  )


            Listing:  ./ipcex/semtool.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program        s e m t o o l;


            {   Program       t o  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 ,b a s e u n i x;


            Const      MaxSemValue          =  5 ;


             P r o c e d u r eD 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     :   ' ,f p g e t e r r n o) ;
                H a l t( 1 ) ;
            end   ;


             F u n c t i o ng 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     ,SEM_GETVAL        , S ) ;
            end   ;


             P r o c e d u r eD i s p V a l ( ID , member      :   l o n g i n t) ;
                                                                             640

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___


 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    . s e m _n s e m s
    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     :=  s e m g e t(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 nC r e a t e S e m (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
//    t h e  semmsl      c o n s t a n t s e e m s k e r n e l  s p e c i f i c
{     I f  members     > semmsl      t h e n
        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 si 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 t o  c r e a t e a  new     s e m a p h o r es e t  w i t h  ' ,members      ,'  members      . '*
 *) ;
    C r e a t e S e m:=s e m g e t(key   ,members      ,IPC_CREAT         o r  I P C _E x c l  o r  4 3 8 ) ;
    I f  C r e a t e S e m=-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  t o  Members     -1   do
        s e m c t l(CreateSem       ,c o u n t,SEM_SETVAL        , s e m o p t s) ;
end   ;


 P r o c e d u r el o c k S e m ( 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)    o r  ( member    > GetMemberCount           (ID  ) - 1 )  then
         D o E r r o r ( ' s e m a p h o r emember      o u t  o f   r a n g e') ;
                                                                 641

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
      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 gt o   l o c k member       ' ,member     ,  '   o f  s e m a p h o r e' ,ID  ) ;
      i f  semop    (I d , @ l o c k,1)= -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 dby   one  ' ) ;
      d i s p v a l(ID , Member     ) ;
end   ;


 P r o c e d u r eUnlockSem        ( 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)    o r  ( member    > GetMemberCount           (ID  ) - 1 )  then
         D o E r r o r ( ' s e m a p h o r emember      o u t  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        n o t  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 gt o   u n l o c k member      ' ,member     ,   '  o f  s e m a p h o r e ' ,ID  ) ;
      i f  semop    (I d , @ u n l o c k,1)= -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 dby   one  ' ) ;
      d i s p v a l(ID , Member     ) ;
end   ;


 P r o c e d u r eRemoveSem        ( 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        r e m o v e d')
    e l s e
        D o E r r o r(  'C o u l d n'' t  r e m o v e  s e m a p h o r e') ;
end   ;



 P r o c e d u r eChangeMode         ( 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(  'C o u l d n'' 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 sw e r e :   ' ,semds    .sem _perm      .mode   ) ;
                                                                 642

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
    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 st o  ' ,mode    )
    e l s e
        D o E r r o r(  'C o u l d n'' t   s e t p e r m i s s i o n s') ;
end   ;


 P r o c e d u r eP 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  , '  h a s  ' , c n t, '  Members      ') ;
    For    I : = 0  t o  c n t-1   Do
        D i s p V a l(i d, i ) ;
end   ;


 P r o c e d u r eUSage    ;


 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( o c k)  < member    >  ') ;
    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  )  < mode   > ' ) ;
    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;



 c o n s t i p c k e y= '. '#0;


 b e g i n
    I f  ParamCount        <1   then    USage     ;
    k e y:=  f t o k( @ i p c k e y[ 1 ]O,RD  ( 's ' ) ) ;
    Case     UpCase    ( Paramstr      ( 1 ) [ 1 ] ) o f
      'C  '  :  b e g i n
                 i f paramcount        <>2    then     u s a g e;
                C r e a t e S e m (key   , s t r t o i n(tp a r a m s t r( 2 ) ) ) ;
                end   ;
      'L  '  :  b e g i n
                 i f paramcount        <>2    then     u s a g e;
                ID  := OpenSem       ( k e y) ;
                LockSem       ( ID  ,s t r t o i n t(p a r a m s t r( 2 ) ) ) ;
                                                                 643

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
                                end   ;
                      'U  '  :  b e g i n
                                 i f paramcount        <>2    then     u s a g e;
                                ID  := OpenSem       ( k e y) ;
                                UnLockSem         (ID  , s t r t o i n t(p a r a m s t(r2 ) ) ) ;
                                end   ;
                      'M  '  :  b e g i n
                                 i f paramcount        <>2    then     u s a g e;
                                ID  := OpenSem       ( k e y) ;
                                ChangeMode         ( ID  , s t r t o i n(tp a r a m s t r( 2 ) ) ) ;
                                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___.____________________________________________________________________________________________________________*
 *___________

                14.4.7         semget

    Synopsis:    Return the ID of a semaphore set, possibly creating the set

Declaration:     function  semget(key:  TKey;nsems:  cint;semflg:  cint)  :  cint

    Visibility:   default

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 (635  ), semop (644  ), semctl (639  )
                14.4.8         semop

    Synopsis:    Perform semaphore operation.

Declaration:     function  semop(semid:  cint;sops:  PSEMbuf;nsops:  cuint)  :  cint

    Visibility:   default
                                                                                 644

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
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 (633  ) 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 performed.

                sem__op    The operation to be performed.  The operation depends on the sign of  sem_op:  A
                      positive number is simply added to the current value of the semaphore.  If 0 (zero) is
                      specified, then the process is suspended until the specified semaphore reaches zero.  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 (644  ), semctl (639  )
                14.4.9         shmat

    Synopsis:    Attach a shared memory block.

Declaration:     function  shmat(shmid:  cint;shmaddr:  pointer;shmflg:  cint)  :  pointer

    Visibility:   default

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 constants:


                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 memory
                       is attached for read-write.  The process then needs read-write permissions to access the
                       shared memory.


                For an example, see shmctl (646  ).

       Errors:   If an error occurs, -1 is returned, and IPCerror is set.

    See also:    shmget (648  ), shmdt (648  ), shmctl (646  )



                                                                                 645

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
                14.4.10          shmctl

    Synopsis:    Perform control operations on a shared memory block.

Declaration:     function  shmctl(shmid:  cint;cmd:  cint;buf:  PShmid_DS)  :  cint

    Visibility:   default

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 :


                IPC__STAT        shmctl fills the TSHMid_ds record that buf points to with the available informa-
                       tion 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 (648  ), shmat (645  ), shmdt (648  )


                Listing:  ./ipcex/shmtool.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program        s h m t o o l;


                 u s e s i p c ,s t r i n g s,B a s e u n i x;


                Const      S e g S i z e =  1 0 0 ;


                 v a r  k e y  :  Tkey   ;
                       shmid    , c n t r  :  l o n g i n t;
                        s e g p t r :  p c h a r;


                 P r o c e d u r eUSage    ;


                 b e g i n
                  W r i t e l n ( ' Usage     :   s h m t o o lw ( r i t e)   t e x t') ;
                  w r i t e l n ( '                             r( e a d) ' ) ;
                  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 g e)  mode   ' ) ;
                  h a l t( 1 ) ;
                end   ;


                 P r o c e d u r eWriteshm        (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   ;


                 P r o c e d u r eReadshm     ( 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 ) ;



                                                                                 646

_________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___
end   ;


 P r o c e d u r eremoveshm        ( 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   ;


 P r o c e d u r eCHangeMode         ( ID   :   l o n g i n t; mode     :   S t r i n g) ;


Var    m   :  word    ;
        c o d e :   i n t e g e r;
        d a t a :   TSHMid _ds      ;


 b e g i n
    v a l  ( mode   ,m , c o d e) ;
    i f  code   <>0    then
        u s a g e;
    I f  s h m c t l ( shmid    ,IPC _STAT      ,@data    )=-1     then
        b e g i n
         w r i t e l n ( ' E r r o r :   s h m c t l : ' ,f p g e t e r r n o) ;
         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 a. shm _perm     . mode   ) ;
    d a t a. shm _perm     .mode   := m  ;
    I f  s h m c t l ( shmid    , IPC _SET    , @data   )=-1     then
        b e g i n
        w r i t e l n(  'E r r o r  :  s h m c t l : ' ,f p g e t e r r n o) ;
        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 a. shm _perm     . mode   ) ;
end   ;


 c o n s t f t o k p a t h=    '. '#0;


 b e g i n
    i f  paramcount        <1   then     u s a g e;
      k e y : =   f t o k  (p c h a r( @ f t o k p a t h[ 1 ] )o,r d ( 'S ' ) ) ;
    s h m i d : =   shmget    ( key  , s e g s i z e,IPC_CREAT        o r  IPC _EXCL       o r  4 3 8 ) ;
    I f  s h m i d=-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. O p e n i n g a s   c l i e n t') ;
       s h m i d  : =  shmget     (key   , s e g s i z e, 0 ) ;
        I f  s h m i d =  -1    then
           b e g i n
           W r i t e l n ( 'shmget       :  E r r o r  ! ', f p g e t e r r n)o;
           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 gnew     s h a r e d memory      s e g m e n t.' ) ;
    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 ! ' , f p g e t e r r n)o;
        h a l t( 1 ) ;
       end   ;
                                                                 647

                _________________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________
                    c a s e  u p c a s e(p a r a m s t r( 1 ) [ 1 ] )o f
                        '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 '   :  r e a d s h m ( shmid    ,s e g p t r) ;
                        'D '   :  removeshm       (s h m i d) ;
                        '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___.____________________________________________________________________________________________________________*
 *___________

                14.4.11          shmdt

    Synopsis:    Detach shared memory block.

Declaration:     function  shmdt(shmaddr:  pointer)  :  cint

    Visibility:   default

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 (645  ).

                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 (648  ), shmat (645  ), shmctl (646  )
                14.4.12          shmget

    Synopsis:    Return the ID of a shared memory block, possibly creating it

Declaration:     function  shmget(key:  TKey;size:  size_t;flag:  cint)  :  cint

    Visibility:   default

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.


                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 bytes in it.

       Errors:   On error, -1 is returned, and IPCError is set.
                                                                                 648


Chapter   15


Reference   for   unit   'keyboard'
15.1          Unix  specific  notes


On  Unix,  applications  run  on  a  "terminal",  and  the  application  writes  to  the  screen  and
reads from the keyboard by communicating with the terminal.  Unix keyboard handling is
mostly  backward  compatible  with  the  DEC  vt100  and  vt220  terminals  from  tens  of  years
ago.  The vt100 and vt220 had very different keyboards than todays PC's and this is where
the problems start.  To make it worse the protocol of both terminals has not been very well
designed.

Because  of  this,  the  keyboard  unit  on  Unix  operating  systems  does  a  best  effort  to  pro-
vide keyboard functionality.  An implementation with full keyboard facilities like on other
operating systems is not possible.

The exception is the Linux kernel.  The terminal emulation of the Linux kernel is from a PC
keyboard viewpoint hopeless as well, but unlike other terminal emulators it is configurable.
On the Linux console, the Free Pascal keyboard unit tries to implement full functionality.

Users of applications using the keyboard unit should expect the following:


     o  Full functionality on the Linux console.  It must be the bare console, SSH into another
        machine will kill the full functionality.

     o  Limited functionality otherwise.


Notes about Linux full functionality:


     o  The keyboard is reprogrammed.  If the keyboard is for whatever reason not restored in
        its original state, please load your keymap to reinitialize it.

     o  Alt+function  keys  generate  keycodes  for  those  keys.  To  switch  virtual  consoles,  use
        ctrl+alt+function key.

     o  Unlike what you're used to with other Unix software, escape works as you intuitively
        expect, it generates the keycode for an escape key without a delay.


The limited functionality does include these quirks:


     o  Escape must be pressed two times before it has effect.

     o  On the Linux console, when the users runs the program by logging into another ma-
        chine:



                                                             649

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
           -  Shift+F1 and Shift+F12 will generate keycodes for F11 and F12.

           -  Shift+arrow keys, shift+ins, shift+del, shift+home, shift+end do not work.  The
              same is true about the control and alt combinations.

           -  Alt+function keys will switch virtual consoles instead of generating the right key
              sequences.

           -  Ctrl+function keys will generate the keycodes for the function keys without ctrl


     o In Xterm:


           -  Shift+insert pastes the x clipboard, no keycode will be generated.


     o In Konsole:


           -  Shift+insert pastes the x clipboard, no keycode will be generated.

           -  Shift+arrow keys doesn't work, nor does ctrl+arrow keys


If  you  have  a  non-standard  terminal,  some  keys  may  not  work  at  all.   When  in  limited
functionality mode, the user can work around using an escape prefix:


     o Esc+1 = F1, Esc+2 = F2.

     o Esc before another key is equal to alt+key.


In such cases, if the terminal does output an escape sequence for those keys, please submit
a bug report so we can add them.
15.2          Writing  a  keyboard  driver


Writing a keyboard driver means that hooks must be created for most of the keyboard unit
functions.  The TKeyBoardDriver record contains a field for each of the possible hooks:


TKeyboardDriver  =  Record
    InitDriver  :  Procedure;
    DoneDriver  :  Procedure;
    GetKeyEvent  :  Function  :  TKeyEvent;
    PollKeyEvent  :  Function  :  TKeyEvent;
    GetShiftState  :  Function  :  Byte;
    TranslateKeyEvent  :  Function  (KeyEvent:  TKeyEvent):  TKeyEvent;
    TranslateKeyEventUniCode:  Function  (KeyEvent:  TKeyEvent):  TKeyEvent;
end;


The meaning of these hooks is explained below:


InitDriver        Called to initialize and enable the driver.  Guaranteed to be called only once.
        This should initialize all needed things for the driver.

DoneDriver          Called to disable and clean up the driver.  Guaranteed to be called after a call
        to initDriver.  This should clean up all things initialized by InitDriver.

GetKeyEvent            Called by GetKeyEvent (659  ).  Must wait for and return the next key event.
        It should NOT store keys.

                                                                 650

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
PollKeyEvent           Called by PollKeyEvent (664  ).  It must return the next key event if there is
       one.  Should not store keys.

GetShiftState          Called by PollShiftStateEvent (664  ).  Must return the current shift state.

TranslateKeyEvent              Should translate a raw key event to a cOrrect key event, i.e.  should
       fill in the shiftstate and convert function key scancodes to function key keycodes.  If
       the  TranslateKeyEvent  is  not  filled  in,  a  default  translation  function  will  be  called
       which converts the known scancodes from the tables in the previous section to a correct
       keyevent.

TranslateKeyEventUniCode                     Should translate a key event to a unicode key representa-
       tion.


Strictly speaking, only the GetKeyEvent and PollKeyEvent hooks must be implemented for
the driver to function correctly.

The example unit demonstrates how a keyboard driver can be installed.  It takes the installed
driver, and hooks into the GetKeyEvent function to register and log the key events in a file.
This driver can work on top of any other driver, as long as it is inserted in the uses clause after
the real driver unit, and the real driver unit should set the driver record in its initialization
section.

Note that with a simple extension of this unit could be used to make a driver that is capable
of recording and storing a set of keyboard strokes, and replaying them at a later time, so a
'keyboard macro' capable driver.  This driver could sit on top of any other driver.
15.3          Keyboard  scan  codes


Special physical keys are encoded with the DOS scan codes for these keys in the second byte
of the TKeyEvent (656  ) type.  A complete list of scan codes can be found in the below table.
This is the list of keys that is used by the default key event translation mechanism.  When
writing a keyboard driver, either these constants should be returned by the various key event
functions, or the TranslateKeyEvent hook should be implemented by the driver.

A list of scan codes for special keys and combinations with the SHIFT, ALT and CTRL keys
can be found in the following table:  They are for quick reference only.
15.4          Overview


The Keyboard unit implements a keyboard access layer which is system independent.  It can
be used to poll the keyboard state and wait for certain events.  Waiting for a keyboard event
can be done with the GetKeyEvent (659  ) function, which will return a driver-dependent key
event.  This key event can be translated to a interpretable event by the TranslateKeyEvent
(667  ) function.  The result of this function can be used in the other event examining functions.

A custom keyboard driver can be installed using the SetKeyboardDriver (666  ) function.  The
current keyboard driver can be retrieved using the GetKeyboardDriver (658  ) function.  The
last section of this chapter demonstrates how to make a keyboard driver.
15.5          Constants,  types  and  variables



15.5.1         Constants

AltPrefix  :  Byte  =  0



                                                                 651

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
Alt key name index.


CtrlPrefix  :  Byte  =  0


Alt key name index.


errKbdBase  =  1010


Base of keyboard routine error reporting constants.


errKbdInitError  =  errKbdBase  +  0


Failed to initialize keyboard driver


errKbdNotImplemented  =  errKbdBase  +  1


Keyboard driver not implemented.


kbAlt  =  8


Alt key modifier


kbASCII  =  $00


Ascii code key event


kbCtrl  =  4


Control key modifier


kbdApps  =  $FF17


Application key (popup-menu) pressed.


kbdDelete  =  $FF2A


Delete key pressed


kbdDown  =  $FF27


Arrow down key pressed


kbdEnd  =  $FF26


End key pressed


kbdF1  =  $FF01


F1 function key pressed.


kbdF10  =  $FF0A



                                                                 652

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
F10 function key pressed.


kbdF11  =  $FF0B


F12 function key pressed.


kbdF12  =  $FF0C


F12 function key pressed.


kbdF13  =  $FF0D


F13 function key pressed.


kbdF14  =  $FF0E


F14 function key pressed.


kbdF15  =  $FF0F


F15 function key pressed.


kbdF16  =  $FF10


F16 function key pressed.


kbdF17  =  $FF11


F17 function key pressed.


kbdF18  =  $FF12


F18 function key pressed.


kbdF19  =  $FF13


F19 function key pressed.


kbdF2  =  $FF02


F2 function key pressed.


kbdF20  =  $FF14


F20 function key pressed.


kbdF3  =  $FF03


F3 function key pressed.


kbdF4  =  $FF04



                                                                 653

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
F4 function key pressed.


kbdF5  =  $FF05


F5 function key pressed.


kbdF6  =  $FF06


F6 function key pressed.


kbdF7  =  $FF07


F7 function key pressed.


kbdF8  =  $FF08


F8 function key pressed.


kbdF9  =  $FF09


F9 function key pressed.


kbdHome  =  $FF20


Home key pressed


kbdInsert  =  $FF29


Insert key pressed


kbdLeft  =  $FF23


Arrow left key pressed


kbdLWin  =  $FF15


Left windows key pressed.


kbdMiddle  =  $FF24


Middle key pad key pressed (numerical 5)


kbdPgDn  =  $FF28


Page down key pressed


kbdPgUp  =  $FF22


Page Up key pressed


kbdRight  =  $FF25



                                                                 654

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
Arrow right key pressed


kbdRWin  =  $FF16


Right windows key pressed.


kbdUp  =  $FF21


Arrow up key pressed


kbFnKey  =  $02


function key pressed.


kbLeftShift  =  1


Left shift key modifier


kbPhys  =  $03


Physical key code event


kbReleased  =  $04


Key release event


kbRightShift  =  2


Right shift key modifier


kbShift  =  kbLeftShift  or  kbRightShift


Shift key modifier


kbUniCode  =  $01


Unicode code key event


SAnd  :  String  =  'AND'


This constant is used as the 'And' word in key descriptions.  This constant is used by the key
event description routines.  It can be changed to localize the key descriptions when needed.


ShiftPrefix  :  Byte  =  0


Shift key name index.


SKeyPad  :  Array[0..($FF2F-kbdHome)]  of  String  =  ('Home','Up','PgUp','Left','Middle','Right','End','Down','PgDn','Insert','Del*
 *ete','','','','',''  )


This constant describes all keypad keys.  This constant is used by the key event description
routines.  It can be changed to localize the key descriptions when needed.



                                                                 655

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
SLeftRight  :  Array[1..2]  of  String  =  ('LEFT','RIGHT'  )


This  constant  contains  strings  to  describe  left  and  right  keys.   This  constant  is  used  by
the key event description routines.  It can be changed to localize the key descriptions when
needed.


SScanCode  :  String  =  'Key  with  scancode  '


This  constant  contains  a  string  to  denote  a  scancode  key  event.  This  constant  is  used  by
the key event description routines.  It can be changed to localize the key descriptions when
needed.


SShift  :  Array[1..3]  of  String  =  ('SHIFT','CTRL','ALT'  )


This constant describes the various modifier keys.  This constant is used by the key event
description routines.  It can be changed to localize the key descriptions when needed.


SUnicodeChar  :  String  =  'Unicode  character  '


This  constant  contains  a  string  to  denote  a  unicode  key  event.   This  constant  is  used  by
the key event description routines.  It can be changed to localize the key descriptions when
needed.


SUnknownFunctionKey  :  String  =  'Unknown  function  key  :  '


This  constant  contains  a  string  to  denote  that  an  unknown  function  key  was  found.  This
constant is used by the key event description routines.  It can be changed to localize the key
descriptions when needed.
15.5.2         Types

TKeyboardDriver  =  record
    InitDriver  :  procedure;
    DoneDriver  :  procedure;
    GetKeyEvent  :  function  :  TKeyEvent;
    PollKeyEvent  :  function  :  TKeyEvent;
    GetShiftState  :  function  :  Byte;
    TranslateKeyEvent  :  function(KeyEvent:  TKeyEvent)  :  TKeyEvent;
    TranslateKeyEventUniCode  :  function(KeyEvent:  TKeyEvent)  :  TKeyEvent;
end
The  TKeyboardDriver  record  can  be  used  to  install  a  custom  keyboard  driver  with  the
SetKeyboardDriver (666  ) function.

The various fields correspond to the different functions of the keyboard unit interface.  For
more information about this record see kbddriver (650  )


TKeyEvent  =  Cardinal


The TKeyEvent type is the base type for all keyboard events.

The key stroke is encoded in the 4 bytes of the TKeyEvent type.  The various fields of the
key stroke encoding can be obtained by typecasting the TKeyEvent type to the TKeyRecord
(657  ) type.



                                                                 656

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                TKeyRecord  =  packed  record
                   KeyCode  :  Word;
                   ShiftState  :  Byte;
                   Flags  :  Byte;
                end
                The structure of a TKeyRecord structure is explained in the following table:

                The shift-state can be checked using the various shift-state constants, and the flags in the last
                byte can be checked using one of the kbASCII, kbUniCode, kbFnKey, kbPhys, kbReleased
                constants.

                If there are two keys returning the same char-code, there's no way to find out which one was
                pressed (Gray+ and Simple+).  If it needs to be known which was pressed, the untranslated
                keycodes must be used, but these are system dependent.  System dependent constants may
                be defined to cover those, with possibily having the same name (but different value).
                15.6          Procedures  and  functions



                15.6.1         AddSequence

Declaration:     procedure  AddSequence(const  St:  String;AChar:  Byte;AScan:  Byte)

    Visibility:   default
                15.6.2         DoneKeyboard

    Synopsis:    Deactivate keyboard driver.

Declaration:     procedure  DoneKeyboard

    Visibility:   default

Description:     DoneKeyboard de-initializes the keyboard interface if the keyboard driver is active.  If the
                keyboard driver is not active, the function does nothing.

                This will cause the keyboard driver to clear up any allocated memory, or restores the console
                or terminal the program was running in to its initial state before the call to InitKeyBoard
                (662  ).   This  function  should  be  called  on  program  exit.   Failing  to  do  so  may  leave  the
                terminal or console window in an unusable state.  Its exact action depends on the platform
                on which the program is running.

                On Unix the default keyboard driver restores the line ending of system.output to #10.

                For an example, see most other functions.

       Errors:   None.

    See also:    InitKeyBoard (662  )
                15.6.3         FindSequence

Declaration:     function  FindSequence(const  St:  String;var  AChar:  Byte;var  Ascan:  Byte)
                                                     :  Boolean

    Visibility:   default
                                                                                 657

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                15.6.4         FunctionKeyName

    Synopsis:    Return string representation of a function key code.

Declaration:     function  FunctionKeyName(KeyCode:  Word)  :  String

    Visibility:   default

Description:     FunctionKeyName returns a string representation of the function key with code KeyCode.
                This can be an actual function key, or one of the cursor movement keys.

       Errors:   In  case  KeyCode  does  not  contain  a  function  code,  the  SUnknownFunctionKey  string  is
                returned, appended with the KeyCode.

    See also:    ShiftStateToString (667  ), KeyEventToString (663  )


                Listing:  ./kbdex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  FunctionKeyName             f u n c t i o n. }


                Uses     k e y b o a r d;


                Var
                    K   :  T k e y E v e n t;


                 b e g i n
                    I n i t K e y b o a r;d
                    W r i t e l n(' P r e s s f u n c t i o n k e y s,  p r e s s " q "   t o  end  . ' ) ;
                    Repeat
                       K :=  G e t K e y E v e n;t
                       K :=  T r a n s l a t e K e y E v e(nKt) ;
                        I f  I s F u n c t i o n K e(yk)  then
                           b e g i n
                           Write    ( 'Got    f u n c t i o n k e y  :   ') ;
                           W r i t e l n(FunctionKeyName           ( T k e y R e c o r(dK ) .KeyCode      ) ) ;
                           end  ;
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyboard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.5         GetKeyboardDriver

    Synopsis:    Return the current keyboard driver record.

Declaration:     procedure  GetKeyboardDriver(var  Driver:  TKeyboardDriver)

    Visibility:   default

Description:     GetKeyBoardDriver returns in Driver the currently active keyboard driver.  This function
                can be used to enhance an existing keyboarddriver.

                For more information on getting and setting the keyboard driver kbddriver (650  ).

       Errors:   None.

    See also:    SetKeyboardDriver (666  )

                                                                                 658

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                15.6.6         GetKeyEvent

    Synopsis:    Get the next raw key event, wait if needed.

Declaration:     function  GetKeyEvent  :  TKeyEvent

    Visibility:   default

Description:     GetKeyEvent returns the last keyevent if one was stored in PendingKeyEvent, or waits for
                one if none is available.  A non-blocking version is available in PollKeyEvent (664  ).

                The  returned  key  is  encoded  as  a  TKeyEvent  type  variable,  and  is  normally  the  physical
                key scan code, (the scan code is driver dependent) which can be translated with one of the
                translation  functions  TranslateKeyEvent  (667  )  or  TranslateKeyEventUniCode  (667  ).   See
                the types section for a description of how the key is described.

       Errors:   If no key became available (e.g.  when the driver does not support it), 0 is returned.

    See also:    PutKeyEvent (665  ), PollKeyEvent (664  ), TranslateKeyEvent (667  ), TranslateKeyEventU-
                niCode (667  )


                Listing:  ./kbdex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t K e y E v e n tf u n c t i o n }


                 u s e s k e y b o a r d;


                Var
                    K   :  TKeyEvent       ;


                 b e g i n
                    I n i t K e y B o a r;d
                    W r i t e l n(' P r e s s k e y s,   p r e s s " q "  t o  end   . ') ;
                    Repeat
                       K :=  G e t K e y E v e n;t
                       K :=  T r a n s l a t e K e y E v e(nKt) ;
                       Write    ( ' Got    k e y  e v e n t w i t h  ' ) ;
                       Case     G e t K e y E v e n t F l a g(sK)  o f
                           k b A S C I I      :   W r i t e l n('A S C I I  k e y' ) ;
                           kbUniCode          :   W r i t e l n('U n i c o d e k e y ') ;
                           kbFnKey            :   W r i t e l n('F u n c t i o n k e y ') ;
                           kbPhys             :   W r i t e l n(' P h y s i c a lk e y ') ;
                           k b R e l e a s e d:   W r i t e l n('R e l e a s e d k e y  e v e n t' ) ;
                       end   ;
                        W r i t e l n('Got    k e y  :   ' ,K e y E v e n t T o S t r i n(gK) ) ;
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyBoard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.7         GetKeyEventChar

    Synopsis:    Get the character key part of a key event.

Declaration:     function  GetKeyEventChar(KeyEvent:  TKeyEvent)  :  Char

    Visibility:   default
                                                                                 659

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
Description:     GetKeyEventChar returns the charcode part of the given KeyEvent, if it contains a translated
                character key keycode.  The charcode is simply the ascii code of the character key that was
                pressed.

                It returns the null character if the key was not a character key, but e.g.  a function key.

                For an example, see GetKeyEvent (659  )

       Errors:   None.

    See also:    GetKeyEventUniCode (662  ), GetKeyEventShiftState (661  ), GetKeyEventFlags (661  ), GetKeyEvent-
                Code (660  ), GetKeyEvent (659  )
                15.6.8         GetKeyEventCode

    Synopsis:    Translate function key part of a key event code.

Declaration:     function  GetKeyEventCode(KeyEvent:  TKeyEvent)  :  Word

    Visibility:   default

Description:     GetKeyEventCode returns the translated function keycode part of the given KeyEvent, if it
                contains a translated function key.

                If the key pressed was not a function key, the null character is returned.

       Errors:   None.

    See also:    GetKeyEventUniCode (662  ), GetKeyEventShiftState (661  ), GetKeyEventFlags (661  ), GetKeyEventChar
                (659  ), GetKeyEvent (659  )


                Listing:  ./kbdex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t K e y E v e n t C o d ef u n c t i o.n }


                Uses     k e y b o a r d;


                Var
                    K   :  TKeyEvent       ;


                 b e g i n
                    I n i t K e y B o a r;d
                    W r i t e l n(' P r e s s f u n c t i o n k e y s,  o r   p r e s s " q "  t o  end   . ') ;
                    Repeat
                       K :=  G e t K e y E v e n;t
                       K :=  T r a n s l a t e K e y E v e(nKt) ;
                        I f  ( G e t K e y E v e n t F l a(gKs)<>  KbfnKey     )   then
                           W r i t e l n(' Not    a  f u n c t i o n k e y' )
                        e l s e
                           b e g i n
                           Write    ( 'Got    k e y  ( ' ,G e t K e y E v e n t C o d(eK) ) ;
                           W r i t e l n(' )  :   ' ,K e y E v e n t T o S t r i n(gK) ) ;
                           end  ;
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyboard         ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 660

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                15.6.9         GetKeyEventFlags

    Synopsis:    Extract the flags from a key event.

Declaration:     function  GetKeyEventFlags(KeyEvent:  TKeyEvent)  :  Byte

    Visibility:   default

Description:     GetKeyEventFlags returns the flags part of the given KeyEvent.

                For an example, see GetKeyEvent (659  )

       Errors:   None.

    See also:    GetKeyEventUniCode (662  ), GetKeyEventShiftState (661  ), GetKeyEventCode (660  ), GetKeyEventChar
                (659  ), GetKeyEvent (659  )
                15.6.10          GetKeyEventShiftState

    Synopsis:    Return the current state of the shift keys.

Declaration:     function  GetKeyEventShiftState(KeyEvent:  TKeyEvent)  :  Byte

    Visibility:   default

Description:     GetKeyEventShiftState returns the shift-state values of the given KeyEvent.  This can be
                used  to  detect  which  of  the  modifier  keys  Shift,  Alt  or  Ctrl  were  pressed.  If  none  were
                pressed, zero is returned.

                Note  that  this  function  does  not  always  return  expected  results;  In  a  unix  X-Term,  the
                modifier keys do not always work.

       Errors:   None.

    See also:    GetKeyEventUniCode (662  ), GetKeyEventFlags (661  ), GetKeyEventCode (660  ), GetKeyEventChar
                (659  ), GetKeyEvent (659  )


                Listing:  ./kbdex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t K e y E v e n t S h i f t S t a tfeu n c t i o n. }


                Uses     k e y b o a r d;


                Var
                    K   :  TKeyEvent       ;
                    S   :  B y t e;


                 b e g i n
                    I n i t K e y B o a r;d
                    Write    ( 'P r e s s  k e y s c o m b i n e d w i t h CTRL    /SHIFT    / ALT   ') ;
                    W r i t e l n(' ,  o r   p r e s s "q "   t o  end  . ' ) ;
                    Repeat
                       K :=  G e t K e y E v e n;t
                       K :=  T r a n s l a t e K e y E v e(nKt) ;
                       S :=  G e t K e y E v e n t S h i f t S t a(tKe) ;
                        I f  (S =0)    then
                           W r i t e l n('No    s p e c i a l k e y s  p r e s s e d')
                        e l s e
                           b e g i n



                                                                                 661

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                           W r i t e l n(' D e t e c t e d s p e c i a lk e y s  :   ' ,S h i f t S t a t e T o S t r i(nKg, F a l *
 *s e) ) ;
                           W r i t e l n(' Got    k e y  :  ' , K e y E v e n t T o S t r i(nKg) ) ;
                           end  ;
                         U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyboard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.11          GetKeyEventUniCode

    Synopsis:    Return the unicode key event.

Declaration:     function  GetKeyEventUniCode(KeyEvent:  TKeyEvent)  :  Word

    Visibility:   default

Description:     GetKeyEventUniCode returns the unicode part of the given KeyEvent if it contains a trans-
                lated unicode character.

       Errors:   None.

    See also:    GetKeyEventShiftState (661  ), GetKeyEventFlags (661  ), GetKeyEventCode (660  ), GetKeyEventChar
                (659  ), GetKeyEvent (659  )
                15.6.12          InitKeyboard

    Synopsis:    Initialize the keyboard driver.

Declaration:     procedure  InitKeyboard

    Visibility:   default

Description:     InitKeyboard initializes the keyboard driver.  If the driver is already active, it does nothing.
                When the driver is initialized,  it will do everything necessary to ensure the functioning of
                the keyboard, including allocating memory, initializing the terminal etc.

                This function should be called once, before using any of the keyboard functions.  When it is
                called, the DoneKeyboard (657  ) function should also be called before exiting the program or
                changing the keyboard driver with SetKeyboardDriver (666  ).

                On  Unix,  the  default  keyboard  driver  sets  terminal  in  raw  mode.   In  raw  mode  the  line
                feed  behaves  as  an  actual  linefeed,  i.e.   the  cursor  is  moved  down  one  line.   while  the  x
                coordinate does not change.  To compensate, the default keyboard sets driver line ending of
                system.output to #13#10.

                For an example, see most other functions.

       Errors:   None.

    See also:    DoneKeyboard (657  ), SetKeyboardDriver (666  )
                15.6.13          IsFunctionKey

    Synopsis:    Check whether a given event is a function key event.

Declaration:     function  IsFunctionKey(KeyEvent:  TKeyEvent)  :  Boolean

    Visibility:   default

Description:     IsFunctionKey returns True if the given key event in KeyEvent was a function key or not.



                                                                                 662

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
       Errors:   None.

    See also:    GetKeyEvent (659  )


                Listing:__./kbdex/ex7.pp___________________________________________________________________________________________*
 *___________

                program       e x a m p l e 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t K e y E v e n tf u n c t i o n }


                 u s e s k e y b o a r d;


                Var
                    K   :  TKeyEvent       ;


                 b e g i n
                    I n i t K e y B o a r;d
                    W r i t e l n(' P r e s s k e y s,   p r e s s " q "  t o  end   . ') ;
                    Repeat
                       K :=  G e t K e y E v e n;t
                       K :=  T r a n s l a t e K e y E v e(nKt) ;
                        I f  I s F u n c t i o n K e(yK)  then
                           W r i t e l n(' Got    f u n c t i o nk e y  :   ' ,K e y E v e n t T o S t r i n(gK) )
                        e l s e
                           W r i t e l n(' n o t  a  f u n c t i o n k e y. ' ) ;
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyBoard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.14          KeyEventToString

    Synopsis:    Return a string describing the key event.

Declaration:     function  KeyEventToString(KeyEvent:  TKeyEvent)  :  String

    Visibility:   default

Description:     KeyEventToString translates the key event in KeyEvent to a human-readable description
                of the pressed key.  It will use the constants described in the constants section to do so.

                For an example, see most other functions.

       Errors:   If an unknown key is passed, the scancode is returned, prefixed with the SScanCode string.

    See also:    FunctionKeyName (658  ), ShiftStateToString (667  )
                15.6.15          KeyPressed

    Synopsis:    Check event queue for key press

Declaration:     function  KeyPressed  :  Boolean

    Visibility:   default

Description:     KeyPressed  checks  the  keyboard  event  queue  to  see  whether  a  key  event  is  present,  and
                returns True if a key event is available.  This function simply calls PollKeyEvent (664  ) and
                checks for a valid result.

       Errors:   None.

    See also:    PollKeyEvent (664  ), GetKeyEvent (659  )



                                                                                 663

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                15.6.16          PollKeyEvent

    Synopsis:    Get next key event, but does not wait.

Declaration:     function  PollKeyEvent  :  TKeyEvent

    Visibility:   default

Description:     PollKeyEvent checks whether a key event is available, and returns it if one is found.  If no
                event is pending, it returns 0.

                Note  that  this  does  not  remove  the  key  from  the  pending  keys.   The  key  should  still  be
                retrieved from the pending key events list with the GetKeyEvent (659  ) function.

       Errors:   None.

    See also:    PutKeyEvent (665  ), GetKeyEvent (659  )


                Listing:  ./kbdex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e P o l l K e y E v e n tf u n c t i o n }


                 u s e s k e y b o a r d;


                Var
                    K   :  TKeyEvent       ;


                 b e g i n
                    I n i t K e y B o a r;d
                    W r i t e l n(' P r e s s k e y s,   p r e s s " q "  t o  end   . ') ;
                    Repeat
                       K :=  P o l l K e y E v e n;t
                        I f  k<>0    then
                           b e g i n
                           K := G e t K e y E v e n t;
                           K := T r a n s l a t e K e y E v e n(tK) ;
                           w r i t e l n;
                           W r i t e l n(' Got    k e y  :  ' , K e y E v e n t T o S t r i(nKg) ) ;
                           end
                        e l s e
                           w r i t e( '. ' ) ;
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyBoard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.17          PollShiftStateEvent

    Synopsis:    Check current shift state.

Declaration:     function  PollShiftStateEvent  :  TKeyEvent

    Visibility:   default

Description:     PollShiftStateEvent  returns  the  current  shiftstate  in  a  keyevent.  This  will  return  0  if
                there is no key event pending.

       Errors:   None.
                                                                                 664

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
    See also:    PollKeyEvent (664  ), GetKeyEvent (659  )


                Listing:  ./kbdex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e P o l l S h i f t S t a t e E v e nftu n c t i o n }


                 u s e s k e y b o a r d;


                Var
                    K   :  TKeyEvent       ;


                 b e g i n
                    I n i t K e y B o a r;d
                    W r i t e l n(' P r e s s k e y s,   p r e s s " q "  t o  end   . ') ;
                    Repeat
                       K :=  P o l l K e y E v e n;t
                        I f  k<>0    then
                           b e g i n
                           K := P o l l S h i f t S t a t e E v e n;t
                           W r i t e l n(' Got    s h i f t s t a t e  :  ' , S h i f t S t a t e T o S t r i(nKg,F a l s e) ) ;
                           //   Consume       t h e  k e y .
                           K := G e t K e y E v e n t;
                           K := T r a n s l a t e K e y E v e n(tK) ;
                           end
                {        e l s e
                           w r i t e( ' . ' )};
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyBoard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.18          PutKeyEvent

    Synopsis:    Put a key event in the event queue.

Declaration:     procedure  PutKeyEvent(KeyEvent:  TKeyEvent)

    Visibility:   default

Description:     PutKeyEvent adds the given KeyEvent to the input queue.  Please note that depending on
                the  implementation  this  can  hold  only  one  value,  i.e.  when  calling  PutKeyEvent  multiple
                times, only the last pushed key will be remembered.

       Errors:   None

    See also:    PollKeyEvent (664  ), GetKeyEvent (659  )


                Listing:  ./kbdex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e P u t K e y E v e n tf u n c t i o n }


                 u s e s k e y b o a r d;


                Var
                    K ,k2    :  TKeyEvent       ;



                                                                                 665

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________


                 b e g i n
                    I n i t K e y B o a r;d
                         W r i t e l n(' P r e s s k e y s,   p r e s s " q "  t o  end   . ') ;
                    K2  : = 0 ;
                    Repeat
                       K :=  G e t K e y E v e n;t
                        I f  k<>0    then
                           b e g i n
                           i f  ( k2   mod    2 ) = 0  then
                              K2  := K +1
                           e l s e
                              K2  : = 0 ;
                           K := T r a n s l a t e K e y E v e n(tK) ;
                           W r i t e l n(' Got    k e y  :  ' , K e y E v e n t T o S t r i(nKg) ) ;
                           i f  ( K2 <>0)     then
                              b e g i n
                              P u t K e y E v e n t(k2 ) ;
                              K2  := T r a n s l a t e K e y E V e n(tK2 ) ;
                               W r i t e l n('Put    k e y  :   ' ,K e y E v e n t T o S t r i n(gK2) )
                              end
                           end
                    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                    DoneKeyBoard         ;
                end___.____________________________________________________________________________________________________________*
 *___________

                15.6.19          RawReadKey

Declaration:     function  RawReadKey  :  Char

    Visibility:   default
                15.6.20          RawReadString

Declaration:     function  RawReadString  :  String

    Visibility:   default
                15.6.21          RestoreStartMode

Declaration:     procedure  RestoreStartMode

    Visibility:   default
                15.6.22          SetKeyboardDriver

    Synopsis:    Set a new keyboard driver.

Declaration:     function  SetKeyboardDriver(const  Driver:  TKeyboardDriver)  :  Boolean

    Visibility:   default

Description:     SetKeyBoardDriver sets the keyboard driver to Driver, if the current keyboard driver is
                not  yet  initialized.  If  the  current  keyboard  driver  is  initialized,  then  SetKeyboardDriver

                                                                                 666

                ____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________
                does nothing.  Before setting the driver, the currently active driver should be disabled with
                a call to DoneKeyboard (657  ).

                The function returns True if the driver was set, False if not.

                For more information on setting the keyboard driver, see kbddriver (650  ).

       Errors:   None.

    See also:    GetKeyboardDriver (658  ), DoneKeyboard (657  )
                15.6.23          ShiftStateToString

    Synopsis:    Return description of key event shift state

Declaration:     function  ShiftStateToString(KeyEvent:  TKeyEvent;UseLeftRight:  Boolean)
                                                              :  String

    Visibility:   default

Description:     ShiftStateToString returns a string description of the shift state of the key event KeyEvent.
                This can be an empty string.

                The shift state is described using the strings in the SShift constant.

                For an example, see PollShiftStateEvent (664  ).

       Errors:   None.

    See also:    FunctionKeyName (658  ), KeyEventToString (663  )
                15.6.24          TranslateKeyEvent

    Synopsis:    Translate raw event to ascii key event

Declaration:     function  TranslateKeyEvent(KeyEvent:  TKeyEvent)  :  TKeyEvent

    Visibility:   default

Description:     TranslateKeyEvent performs ASCII translation of the KeyEvent.  It translates a physical
                key  to  a  function  key  if  the  key  is  a  function  key,  and  translates  the  physical  key  to  the
                ordinal of the ascii character if there is an equivalent character key.

                For an example, see GetKeyEvent (659  )

       Errors:   None.

    See also:    TranslateKeyEventUniCode (667  )
                15.6.25          TranslateKeyEventUniCode

    Synopsis:    Translate raw event to UNICode key event

Declaration:     function  TranslateKeyEventUniCode(KeyEvent:  TKeyEvent)  :  TKeyEvent

    Visibility:   default

Description:     TranslateKeyEventUniCode performs Unicode translation of the KeyEvent.  It is not yet
                implemented for all platforms.

       Errors:   If the function is not yet implemented, then the ErrorCode of the system unit will be set to
                errKbdNotImplemented

    See also:    TranslateKeyEvent (667  )
                                                                                 667

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___


                                             Table 15.1:  Key Scancodes


       __Code_______Key__________________________Code______Key_____________________Code_______Key______________________
         00         NoKey                       3D         F3                      70         ALT-F9
         01         ALT-Esc                     3E         F4                      71         ALT-F10
         02         ALT-Space                   3F         F5                      72         CTRL-PrtSc
         04         CTRL-Ins                    40         F6                      73         CTRL-Left
         05         SHIFT-Ins                   41         F7                      74         CTRL-Right
         06         CTRL-Del                    42         F8                      75         CTRL-end
         07         SHIFT-Del                   43         F9                      76         CTRL-PgDn
         08         ALT-Back                    44         F10                     77         CTRL-Home
         09         ALT-SHIFT-Back              47         Home                    78         ALT-1
         0F         SHIFT-Tab                   48         Up                      79         ALT-2
         10         ALT-Q                       49         PgUp                    7A         ALT-3
         11         ALT-W                       4B         Left                    7B         ALT-4
         12         ALT-E                       4C         Center                  7C         ALT-5
         13         ALT-R                       4D         Right                   7D         ALT-6
         14         ALT-T                       4E         ALT-GrayPlus            7E         ALT-7
         15         ALT-Y                       4F         end                     7F         ALT-8
         16         ALT-U                       50         Down                    80         ALT-9
         17         ALT-I                       51         PgDn                    81         ALT-0
         18         ALT-O                       52         Ins                     82         ALT-Minus
         19         ALT-P                       53         Del                     83         ALT-Equal
         1A         ALT-LftBrack                54         SHIFT-F1                84         CTRL-PgUp
         1B         ALT-RgtBrack                55         SHIFT-F2                85         F11
         1E         ALT-A                       56         SHIFT-F3                86         F12
         1F         ALT-S                       57         SHIFT-F4                87         SHIFT-F11
         20         ALT-D                       58         SHIFT-F5                88         SHIFT-F12
         21         ALT-F                       59         SHIFT-F6                89         CTRL-F11
         22         ALT-G                       5A         SHIFT-F7                8A         CTRL-F12
         23         ALT-H                       5B         SHIFT-F8                8B         ALT-F11
         24         ALT-J                       5C         SHIFT-F9                8C         ALT-F12
         25         ALT-K                       5D         SHIFT-F10               8D         CTRL-Up
         26         ALT-L                       5E         CTRL-F1                 8E         CTRL-Minus
         27         ALT-SemiCol                 5F         CTRL-F2                 8F         CTRL-Center
         28         ALT-Quote                   60         CTRL-F3                 90         CTRL-GreyPlus
         29         ALT-OpQuote                 61         CTRL-F4                 91         CTRL-Down
         2B         ALT-BkSlash                 62         CTRL-F5                 94         CTRL-Tab
         2C         ALT-Z                       63         CTRL-F6                 97         ALT-Home
         2D         ALT-X                       64         CTRL-F7                 98         ALT-Up
         2E         ALT-C                       65         CTRL-F8                 99         ALT-PgUp
         2F         ALT-V                       66         CTRL-F9                 9B         ALT-Left
         30         ALT-B                       67         CTRL-F10                9D         ALT-Right
         31         ALT-N                       68         ALT-F1                  9F         ALT-end
         32         ALT-M                       69         ALT-F2                  A0         ALT-Down
         33         ALT-Comma                   6A         ALT-F3                  A1         ALT-PgDn
         34         ALT-Period                  6B         ALT-F4                  A2         ALT-Ins
         35         ALT-Slash                   6C         ALT-F5                  A3         ALT-Del
         37         ALT-GreyAst                 6D         ALT-F6                  A5         ALT-Tab
         3B         F1                          6E         ALT-F7
         3C         F2                          6F         ALT-F8


                                                                 668

____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___
                                       Table 15.2:  Special keys scan codes


                       _Key______________Code_______SHIFT-Key___________CTRL-Key___________Alt-Key_______
                         NoKey            00
                         F1               3B        54                  5E                 68
                         F2               3C        55                  5F                 69
                         F3               3D        56                  60                 6A
                         F4               3E        57                  61                 6B
                         F5               3F        58                  62                 6C
                         F6               40        59                  63                 6D
                         F7               41        5A                  64                 6E
                         F8               42        5A                  65                 6F
                         F9               43        5B                  66                 70
                         F10              44        5C                  67                 71
                         F11              85        87                  89                 8B
                         F12              86        88                  8A                 8C
                         Home             47                            77                 97
                         Up               48                            8D                 98
                         PgUp             49                            84                 99
                         Left             4B                            73                 9B
                         Center           4C                            8F
                         Right            4D                            74                 9D
                         end              4F                            75                 9F
                         Down             50                            91                 A0
                         PgDn             51                            76                 A1
                         Ins              52        05                  04                 A2
                         Del              53        07                  06                 A3
                         Tab              8         0F                  94                 A5
                         GreyPlus                                       90                 4E

                                     Table 15.3:  Structure of TKeyRecord



__Field_____________Meaning________________________________________________________________________________________________________*
 *_____________________________________________________________________________________________
  KeyCode           Depending on flags either the physical representation of a key (under DOS scancode, ascii code pair), or the tr*
 *anslated ASCII/unicode character.
  ShiftState        Shift-state when this key was pressed (or shortly after)
  Flags             Determine how to interpret KeyCode



                                                                 669


Chapter   16


Reference   for   unit   'Linux'
16.1          Used  units
                                     Table 16.1:  Used units by unit 'Linux'


                                                  _Name_____________Page______
                                                    BaseUnix            94



16.2          Overview


The linux unit contains linux specific operating system calls.

The platform independent functionality of the FPC 1.0.X version of the linux unit has been
split out over the unix (1547   ), baseunix (94 ) and unixutil (1599   ) units.

The X86-specific parts have been moved to the X86 (1629   ) unit.

People wanting to use the old version (FPC 1.0.X and before) of the linux can use the oldlinux
(942  ) unit instead.
16.3          Constants,  types  and  variables



16.3.1         Constants

CAP_AUDIT_CONTROL  =  30


Allow manipulation of kernel auditing features


CAP_AUDIT_WRITE  =  29


Allow writing to kernel audit log


CAP_CHOWN  =  0


Perform chown operation



                                                             670

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
CAP_DAC_OVERRIDE  =  1


Bypass file operation (rwx) checks


CAP_DAC_READ_SEARCH  =  2


Bypass file read-only operation checks


CAP_FOWNER  =  3


Bypass owner ID checks


CAP_FSETID  =  4


Do not clear SUID/GUID bits on modified files


CAP_FS_MASK  =  $1f


?


CAP_IPC_LOCK  =  14


Allow memory locking calls


CAP_IPC_OWNER  =  15


Bypass permission checks on IPC operations


CAP_KILL  =  5


Bypass permission checks for sending signals


CAP_LEASE  =  28


Allow file leases


CAP_LINUX_IMMUTABLE  =  9


Allow setting ext2 file attributes


CAP_MKNOD  =  27


Allow creation of special files through mknod calls


CAP_NET_ADMIN  =  12


Allow network operations (e.g.  setting socket options)


CAP_NET_BIND_SERVICE  =  10


Allow binding to ports less than 1024



                                                                 671

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
CAP_NET_BROADCAST  =  11


Allow socket broadcast operations


CAP_NET_RAW  =  13


Allow use of RAW and PACKET sockets


CAP_SETGID  =  6


Allow GID manipulations


CAP_SETPCAP  =  8


Allow to set other process' capabilities


CAP_SETUID  =  7


Allow process ID manipulations


CAP_SYS_ADMIN  =  21


Allow various system administration calls


CAP_SYS_BOOT  =  22


Allow reboot calls


CAP_SYS_CHROOT  =  18


Allow chroot calls.


CAP_SYS_MODULE  =  16


Allow loading/unloading of kernel modules


CAP_SYS_NICE  =  23


Allowing raising process and thread priorities


CAP_SYS_PACCT  =  20


Allow acct calls


CAP_SYS_PTRACE  =  19


Allow ptrace calls


CAP_SYS_RAWIO  =  17


Allow raw I/O port operations



                                                                 672

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
CAP_SYS_RESOURCE  =  24


Allow use of special resources or raising of resource limits


CAP_SYS_TIME  =  25


Allow system or real-time clock modification


CAP_SYS_TTY_CONFIG  =  26


Allow vhangup calls


CLONE_CHILD_CLEARTID  =  $00200000


Clone option:  Erase child thread ID in child memory space when child exits.


CLONE_CHILD_SETTID  =  $01000000


Clone option:  Store child thread ID in child memory.


CLONE_DETACHED  =  $00400000


Clone option:  Start clone detached.


CLONE_FILES  =  $00000400


Clone (670  ) option:  open files shared between processes


CLONE_FS  =  $00000200


Clone (670  ) option:  fs info shared between processes


CLONE_NEWNS  =  $00020000


Clone options:  Start child in new (filesystem) namespace.


CLONE_PARENT  =  $00008000


Clone options:  Set child parent to parent of calling process.


CLONE_PARENT_SETTID  =  $00100000


Clone option:  Store child thread ID in memory in both parent and child.


CLONE_PID  =  $00001000


Clone (670  ) option:  PID shared between processes


CLONE_PTRACE  =  $00002000


Clone options:  if parent is traced, trace child also



                                                                 673

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
CLONE_SETTLS  =  $00080000


Clone option:  The newtls parameter is the TLS descriptor of the child


CLONE_SIGHAND  =  $00000800


Clone (670  ) option:  signal handlers shared between processes


CLONE_STOPPED  =  $02000000


Clone option:  Start child in stopped state.


CLONE_SYSVSEM  =  $00040000


Clone option:  Caller and child share the same semaphore undo values


CLONE_THREAD  =  $00010000


Clone options:  Set child in thread group of calling process.


CLONE_UNTRACED  =  $00800000


Clone option:  Do not allow a ptrace call on this clone.


CLONE_VFORK  =  $00004000


Clone options:  suspend parent till child execs


CLONE_VM  =  $00000100


Clone (670  ) option:  VM shared between processes


CSIGNAL  =  $000000ff


Clone (670  ) option:  Signal mask to be sent at exit


EPOLLERR  =  $08


Poll error condition


EPOLLET  =  $80000000


Undocumented


EPOLLHUP  =  $10


Poll hung up


EPOLLIN  =  $01


Poll input file descriptor ready event



                                                                 674

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
EPOLLOUT  =  $04


Poll output file descriptor ready event


EPOLLPRI  =  $02


Priority data available on input file descriptor


EPOLL_CTL_ADD  =  1


Add filedescriptor to list of events


EPOLL_CTL_DEL  =  2


Delete event for filedescriptor


EPOLL_CTL_MOD  =  3


Modify event for filedescriptor


FUTEX_CMP_REQUEUE  =  4


Futex option:  requeue waiting processes on other futex, but check it's value first


FUTEX_FD  =  2


Futex option:  Associate file descriptor with futex.


FUTEX_LOCK_PI  =  6


Futex option:  Undocumented


FUTEX_OP_ADD  =  1


Futex operation:  Undocumented


FUTEX_OP_ANDN  =  3


Futex operation:  Undocumented


FUTEX_OP_CMP_EQ  =  0


Futex operation:  Undocumented


FUTEX_OP_CMP_GE  =  5


Futex operation:  Undocumented


FUTEX_OP_CMP_GT  =  4


Futex operation:  Undocumented



                                                                 675

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
FUTEX_OP_CMP_LE  =  3


Futex operation:  Undocumented


FUTEX_OP_CMP_LT  =  2


Futex operation:  Undocumented


FUTEX_OP_CMP_NE  =  1


Futex operation:  Undocumented


FUTEX_OP_OPARG_SHIFT  =  8


Futex operation:  Undocumented


FUTEX_OP_OR  =  2


Futex operation:  Undocumented


FUTEX_OP_SET  =  0


Futex operation:  Undocumented


FUTEX_OP_XOR  =  4


Futex operation:  Undocumented


FUTEX_REQUEUE  =  3


Futex option:  requeue waiting processes on other futex.


FUTEX_TRYLOCK_PI  =  8


Futex option:  Undocumented


FUTEX_UNLOCK_PI  =  7


Futex option:  Undocumented


FUTEX_WAIT  =  0


Futex option:  Wait on futex till wake call arrives.


FUTEX_WAKE  =  1


Futex option:  wakes any waiting processes on this futex


FUTEX_WAKE_OP  =  5


Futex option:  Undocumented



                                                                 676

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
GIO_CMAP  =  $4B70


IOCTL: Get colour palette on VGA+


GIO_FONT  =  $4B60


IOCTL: Get font in expanded form.


GIO_FONTX  =  $4B6B


IOCTL: Get font in consolefontdesc record.


GIO_SCRNMAP  =  $4B40


IOCTL: get screen mapping from kernel


GIO_UNIMAP  =  $4B66


IOCTL: get unicode-to-font mapping from kernel


GIO_UNISCRNMAP  =  $4B69


IOCTL: get full Unicode screen mapping


KB_101  =  2


IOCTL: Keyboard types:  101 keys


KB_84  =  1


IOCTL: Keyboard types:  84 keys


KB_OTHER  =  3


IOCTL: Keyboard types:  other type


KDADDIO  =  $4B34


IOCTL: add i/o port as valid


KDDELIO  =  $4B35


IOCTL: delete i/o port as valid


KDDISABIO  =  $4B37


IOCTL: disable i/o to video board


KDENABIO  =  $4B36


IOCTL: enable i/o to video board



                                                                 677

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
KDFONTOP  =  $4B72


IOCTL: font operations


KDGETKEYCODE  =  $4B4C


IOCTL: read kernel keycode table entry


KDGETLED  =  $4B31


IOCTL: return current led state


KDGETMODE  =  $4B3B


IOCTL: get current mode


KDGKBDIACR  =  $4B4A


IOCTL: read kernel accent table


KDGKBTYPE  =  $4B33


IOCTL: get keyboard type


KDMAPDISP  =  $4B3C


IOCTL: map display into address space


KDMKTONE  =  $4B30


IOCTL: generate tone


KDSETKEYCODE  =  $4B4D


IOCTL: write kernel keycode table entry


KDSETLED  =  $4B32


IOCTL: set led state


KDSETMODE  =  $4B3A


IOCTL: set text/graphics mode


KDSIGACCEPT  =  $4B4E


IOCTL: accept kbd generated signals


KDSKBDIACR  =  $4B4B


IOCTL: write kernel accent table



                                                                 678

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
KDUNMAPDISP  =  $4B3D


IOCTL: unmap display from address space


KD_GRAPHICS  =  1


IOCTL: Tty modes:  graphics mode


KD_TEXT  =  0


IOCTL: Tty modes:  Text mode


KD_TEXT0  =  2


IOCTL: Tty modes:  Text mode (obsolete)


KD_TEXT1  =  3


IOCTL: Tty modes:  Text mode (obsolete)


KIOCSOUND  =  $4B2F


IOCTL: start/stop sound generation (0 for off)


LED_CAP  =  4


IOCTL: LED_CAP : caps lock led


LED_NUM  =  2


IOCTL: LED_SCR : Num lock led


LED_SCR  =  1


IOCTL: LED_SCR : scroll lock led


LINUX_CAPABILITY_VERSION  =  $19980330


Current capability version in use by kernel


MAP_DENYWRITE  =  $800


Read-only


MAP_EXECUTABLE  =  $1000


Memory area is marked as executable


MAP_GROWSDOWN  =  $100


Memory map grows down, like stack



                                                                 679

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
MAP_LOCKED  =  $2000


Memory pages are locked


MAP_NORESERVE  =  $4000


Do not check for reservations


MODIFY_LDT_CONTENTS_CODE  =  2


Modify_ldt option:  Undocumented


MODIFY_LDT_CONTENTS_DATA  =  0


Modify_ldt option:  Undocumented


MODIFY_LDT_CONTENTS_STACK  =  1


Modify_ldt option:  Undocumented


PIO_CMAP  =  $4B71


IOCTL: Set colour palette on VGA+


PIO_FONT  =  $4B61


IOCTL: Use font in expanded form.


PIO_FONTRESET  =  $4B6D


IOCTL: Reset to default font


PIO_FONTX  =  $4B6C


IOCTL: Set font in consolefontdesc record.


PIO_SCRNMAP  =  $4B41


IOCTL: put screen mapping table in kernel


PIO_UNIMAP  =  $4B67


IOCTL: put unicode-to-font mapping in kernel


PIO_UNIMAPCLR  =  $4B68


IOCTL: clear table, possibly advise hash algorithm


PIO_UNISCRNMAP  =  $4B6A


IOCTL: set full Unicode screen mapping



                                                                 680

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
SPLICE_F_GIFT  =  8


Pages spliced in are a gift


SPLICE_F_MORE  =  4


Expect more data


SPLICE_F_MOVE  =  1


Move pages instead of copying


SPLICE_F_NONBLOCK  =  2


Don't block on pipe splicing operations


UD_CONTENTS_CODE  =  MODIFY_LDT_CONTENTS_CODE  shl  1


TLS segment descriptor:  Undocumented


UD_CONTENTS_DATA  =  MODIFY_LDT_CONTENTS_DATA  shl  1


TLS segment descriptor:  Undocumented


UD_CONTENTS_STACK  =  MODIFY_LDT_CONTENTS_STACK  shl  1


TLS segment descriptor:  Undocumented


UD_LIMIT_IN_PAGES  =  $10


TLS segment descriptor:  Undocumented


UD_LM  =  $80


TLS segment descriptor:  Undocumented


UD_READ_EXEC_ONLY  =  $08


TLS segment descriptor:  Undocumented


UD_SEG_32BIT  =  $01


TLS segment descriptor :  Undocumented


UD_SEG_NOT_PRESENT  =  $20


TLS segment descriptor:  Undocumented


UD_USEABLE  =  $40


TLS segment descriptor:  Undocumented



                                                                 681

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
16.3.2         Types

EPoll_Data  =  record
end
Data structure used in EPOLL IOCTL call.


EPoll_Event  =  record
    Events  :  cuint32;
    Data  :  TEPoll_Data;
end
Structure used in epoll_ctl (685  ) call.


PEPoll_Data  =  ^EPoll_Data


Pointer to EPoll_Data (682  ) record


PEpoll_Event  =  ^EPoll_Event


Pointer to EPoll_Event (682  ) type


PSysInfo  =  ^TSysInfo


Pointer to TSysInfo (683  ) record.


Puser_cap_data  =  ^user_cap_data


Pointer to user_cap_data (683  ) record


Puser_cap_header  =  ^user_cap_header


Pointer to user_cap_header (683  ) record


PUser_Desc  =  ^user_desc


PUser_Desc is a pointer to the user_desc (683  ) type.


TCloneFunc  =  function(args:  pointer)  :  LongInt


Clone function prototype.


TEPoll_Data  =  EPoll_Data


Alias for EPoll_Data (682  ) type


TEPoll_Event  =  EPoll_Event


Alias for EPoll_Event (682  ) type



                                                                 682

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
TSysInfo  =  record
   uptime  :  clong;
   loads  :  Array[0..2]  of  culong;
   totalram  :  culong;
   freeram  :  culong;
   sharedram  :  culong;
   bufferram  :  culong;
   totalswap  :  culong;
   freeswap  :  culong;
   procs  :  cushort;
   pad  :  cushort;
   totalhigh  :  culong;
   freehigh  :  culong;
   mem_unit  :  cuint;
   _f  :  Array[0..19-2*sizeof(clong)-sizeof(cint)]  of  cchar;
end
Record with system information, used by the SysInfo (686  ) call.


TUser_Desc  =  user_desc


TUser_Desc is an alias for the user_desc (683  ) type.


user_cap_data  =  packed  record
   effective  :  cardinal;
   permitted  :  cardinal;
   inheritable  :  cardinal;
end
user_cap_data describes the set of capabilities for the indicated thread.


user_cap_header  =  packed  record
   version  :  cardinal;
   pid  :  cardinal;
end
user_cap_header describes the root user capabilities for the current thread, as set by getcap
(670  ) and setcap (670  )


user_desc  =  packed  record
   entry_number  :  cint;
   base_addr  :  cuint;
   limit  :  cuint;
   flags  :  cuint;
end
user_desc is the TLS (Thread Local Storage) segment descriptor used in the Clone call.  It
should not be used, as it contains highly kernel-specific data.



                                                                 683

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________
                16.4          Procedures  and  functions



                16.4.1         capget

    Synopsis:    Return the capabilities for the indicated thread

Declaration:     function  capget(header:  Puser_cap_header;data:  Puser_cap_data)  :  cint

    Visibility:   default

Description:     capget returns the capabilities of the indicated thread in header.  The thread is identified
                by the process ID, or -1 for all caller (and child) process ID's.

                Refer to the linux man pages (7 capabilities) for more info.

       Errors:   On success, zero is returned, on error -1 is returned, and fperrno is set to the error.

    See also:    capset (684  )
                16.4.2         capset

    Synopsis:    Set the capabilities for the indicated thread

Declaration:     function  capset(header:  Puser_cap_header;data:  Puser_cap_data)  :  cint

    Visibility:   default

Description:     capget sets the capabilities of the indicated thread in header.  The thread is identified by
                the process ID, or -1 for all caller (and child) process ID's.

                Refer to the linux man pages (7 capabilities) for more info.

       Errors:   On success, zero is returned, on error -1 is returned, and fperrno is set to the error.

    See also:    capget (684  )
                16.4.3         epoll__create

    Synopsis:    Create new epoll file descriptor

Declaration:     function  epoll_create(size:  cint)  :  cint

    Visibility:   default

Description:     epoll_create creates a new epoll file descriptor.  The size argument indicates to the kernel
                approximately how many structures should be allocated, but is by no means an upper limit.

                On  success,  a  file  descriptor  is  returned  that  can  be  used  in  subsequent  epoll_ctl  (685  )  or
                epoll_wait (685  ) calls, and should be closed using the fpClose (136  ) call.

       Errors:   On error, -1 is returned, and errno (94 ) is set.

    See also:    epoll_ctl (685  ), epoll_wait (685  ), #rtl.baseunix.fpClose (136  )
                                                                                 684

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________
                16.4.4         epoll__ctl

    Synopsis:    Modify an epoll file descriptor

Declaration:     function  epoll_ctl(epfd:  cint;op:  cint;fd:  cint;event:  PEpoll_Event)
                                                :  cint

    Visibility:   default

Description:     epoll_ctl performs the op operation on epoll file descriptor epfd.  The operation will be
                monitored on file descriptor fd, and is optionally controlled by event.

                op can be one of the following values:


                EPOLL__CTL__ADD               Add filedescriptor to list of events

                EPOLL__CTL__MOD                Modify event for filedescriptor

                EPOLL__CTL__DEL              Delete event for filedescriptor


                The events field in event_data is a bitmask of one or more of the following values:


                EPOLLIN         The file is ready for read operations

                EPOLLOUT            The file is ready for write operations.

                EPOLLPRI           Urgent data is available for read operations.

                EPOLLERR            An error condition is signaled on the file descriptor.

                EPOLLHUP            A Hang up happened on the file descriptor.

                EPOLLET          Set the Edge Triggered behaviour for the file descriptor.

                EPOLLONESHOT                  Set One-Shot behaviour for the file descriptor.  The event will be trig-
                       gered only once.


       Errors:   On error -1 is returned, and errno is set accordingly.

    See also:    epoll_create (684  ), epoll_wait (685  ), #rtl.baseunix.fpClose (136  )
                16.4.5         epoll__wait

    Synopsis:    Wait for an event on an epoll file descriptor.

Declaration:     function  epoll_wait(epfd:  cint;events:  PEpoll_Event;maxevents:  cint;
                                                timeout:  cint)  :  cint

    Visibility:   default

Description:     epoll_wait  waits  for  timeout  milliseconds  for  an  event  to  occur  on  epoll  file  descriptor
                epfd.  If  timeout is -1, it waits indefinitely, if  timeour is zero, it does not wait, but returns
                immediatly, even if no events were detected.

                On return, data for at most maxevents will be returned in the memory pointed to by events.
                The function returns the number of file descriptors for which events were reported.  This can
                be zero if the timeout was reached.

       Errors:   On error -1 is returned, and errno is set accordingly.

    See also:    epoll_create (684  ), epoll_ctl (685  ), #rtl.baseunix.fpClose (136  )

                                                                                 685

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________
                16.4.6         futex__op

    Synopsis:    Futex operation:

Declaration:     function  futex_op(op:  cint;oparg:  cint;cmp:  cint;cmparg:  cint)  :  cint

    Visibility:   default

Description:     FUTEX_OP Performs an operation on a futex:


                FUTEX_OP  :=  ((op  and  $F)  shl  28)  or
                                    ((cmp  and  $F)  shl  24)  or
                                    ((oparg  and  $FFF)  shl  12)
                                    or  (cmparg  and  $FFF);
                16.4.7         Sysinfo

    Synopsis:    Return kernel system information

Declaration:     function  Sysinfo(Info:  PSysInfo)  :  cint

    Visibility:   default

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.

                totalswap      total amount of swapspace.

                freeswap      amount of free swapspace.

                procs    number of current processes.


       Errors:   None.

    See also:    #rtl.baseunix.fpUname (179  )


                Listing:  ./linuxex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 6 4;


                {   Example       t o  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.
                    S y s i n f o i s  L i n u x- o n l y.  }


                {  $ i f d e f L i n u x}
                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;



                                                                                 686

_____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___
       D ,M  ,S e c s ,H   :  l o n g i n t;
{ $ e n d i f}


 b e g i n
    { $ i f d e f L i n u x}
    I f  Not    S y s I n f o(I n f o)   then
       H a l t ( 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('L o a d s    :  ' ,L o a d s[ 1 ] ,' / ' ,L o a d s[ 2 ] ,'/  ', L o a d s[ 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   ;
    { $ e n d i f}
end___._______________________________________________________________________________________________________________________



                                                                 687


Chapter   17


Reference   for   unit   'math'
17.1          Geometrical  functions
                                                       Table 17.1:

                                    __Name_______________Description_______________________
                                      hypot (705  )       Hypotenuse of triangle
                                      norm (717  )        Euclidian norm



17.2          Statistical  functions
                                                       Table 17.2:

              __Name_____________________________________Description____________________________________________
                mean (713  )                            Mean of values
                meanandstddev (713  )                   Mean and standard deviation of values
                momentskewkurtosis (716  )              Moments, skew and kurtosis
                popnstddev (718  )                      Population standarddeviation
                popnvariance (719  )                    Population variance
                randg (722  )                           Gaussian distributed randum value
                stddev (726  )                          Standard deviation
                sum (727  )                             Sum of values
                sumofsquares (727  )                    Sum of squared values
                sumsandsquares (728  )                  Sum of values and squared values
                totalvariance (730  )                   Total variance of values
                variance (731  )                        variance of values

                                                             688

_____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___

                                                       Table 17.3:

                               _Name_______________Description___________________________________
                                 ceil (698  )       Round to infinity
                                 floor (703  )      Round to minus infinity
                                 frexp (703  )      Return mantissa and exponent

                                                       Table 17.4:

                             __Name____________________Description_______________________________
                               intpower (706  )        Raise float to integer power
                               ldexp (708  )           Calculate $2^p x$
                               lnxp1 (708  )           calculate log(x+1)
                               log10 (709  )           calculate 10-base log
                               log2 (709  )            calculate 2-base log
                               logn (710  )            calculate N-base log
                               power (720  )           raise float to arbitrary power

17.3          Number  converting



17.4          Exponential  and  logarithmic  functions



17.5          Hyperbolic  functions

                                                       Table 17.5:

                          __Name_________________Description________________________________________
                            arcosh (695  )       caculate reverse hyperbolic cosine
                            arsinh (697  )       caculate reverse hyperbolic sine
                            artanh (697  )       caculate reverse hyperbolic tangent
                            cosh (699  )         calculate hyperbolic cosine
                            sinh (725  )         calculate hyperbolic sine
                            tanh (730  )         calculate hyperbolic tangent



17.6          Trigoniometric  functions



17.7          Angle  unit  conversion


Routines to convert angles between different angle units.
17.8          Min/max  determination


Functions to determine the minimum or maximum of numbers:
                                                                 689

_____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___

                                                       Table 17.6:

                                 __Name__________________Description__________________________
                                   arccos (694  )        calculate reverse cosine
                                   arcsin (695  )        calculate reverse sine
                                   arctan2 (696  )       calculate reverse tangent
                                   cotan (700  )         calculate cotangent
                                   sincos (725  )        calculate sine and cosine
                                   tan (729  )           calculate tangent

                                                       Table 17.7:

                              __Name______________________Description___________________________
                                cycletorad (701  )        convert cycles to radians
                                degtograd (701  )         convert degrees to grads
                                degtorad (702  )          convert degrees to radians
                                gradtodeg (704  )         convert grads to degrees
                                gradtorad (705  )         convert grads to radians
                                radtocycle (720  )        convert radians to cycles
                                radtodeg (721  )          convert radians to degrees
                                radtograd (721  )         convert radians to grads

17.9          Used  units



17.10            Overview


This  document  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.
17.11            Constants,  types  and  variables



17.11.1          Constants

EqualsValue  =  0


Values are the same


GreaterThanValue  =  High  (  TValueRelationship  )



                                                                 690

_____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___

                                                       Table 17.8:

                    __Name_________________________Description_____________________________________________
                      max (711  )                   Maximum of 2 values
                      maxIntValue (711  )           Maximum of an array of integer values
                      maxvalue (712  )              Maximum of an array of values
                      min (714  )                   Minimum of 2 values
                      minIntValue (715  )           Minimum of an array of integer values
                      minvalue (716  )              Minimum of an array of values

                                     Table 17.9:  Used units by unit 'math'


                                                   __Name__________Page_____
                                                     sysutils      1356

First values is greater than second value


Infinity  =  1.0  /  0.0


Value is infinity


LessThanValue  =  Low  (  TValueRelationship  )


First value is less than second value


MaxExtended  =  1.1e  +  4932


Maximum value of extended type


MaxFloat  =  MaxExtended


Maximum value of float type


MinExtended  =  3.4e  -  4932


Minimum value (closest to zero) of extended type


MinFloat  =  MinExtended


Minimum value (closest to zero) of float type


NaN  =  0.0  /  0.0


Value is Not a Number


NegativeValue  =  Low  (  TValueSign  )


Value is negative



                                                                 691

_____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___
NegInfinity  =  -1.0  /  0.0


Value is negative (minus) infinity


PositiveValue  =  High  (  TValueSign  )


Value is positive


ZeroValue  =  0


Value is zero
17.11.2          Types

float  =  extended


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 PFloat (692  ) is used in
functions that accept an array of values of arbitrary length.


PFloat  =  ^float


Pointer to Float (692  ) type.


PInteger  =  ObjPas.PInteger


Pointer to integer type


TFPUException  =  (exInvalidOp,exDenormalized,exZeroDivide,exOverflow,
                            exUnderflow,exPrecision)
                      Table 17.10:  Enumeration values for type TFPUException


                                 __Value____________________Explanation_______________________
                                   exDenormalized
                                   exInvalidOp               Invalid operation error
                                   exOverflow                Float overflow error
                                   exPrecision               Precision error
                                   exUnderflow               Float underflow error
                                   exZeroDivide              Division by zero error.
Type describing Floating Point processor exceptions.


TFPUExceptionMask=  Set  of  (exDenormalized,exInvalidOp,exOverflow,
                                             exPrecision,exUnderflow,exZeroDivide)


Type to set the Floating Point Unit exception mask.


TFPUPrecisionMode  =  (pmSingle,pmReserved,pmDouble,pmExtended)



                                                                 692

_____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___

                   Table 17.11:  Enumeration values for type TFPUPrecisionMode


                                  __Value________________Explanation_________________________
                                    pmDouble             Double-type precision
                                    pmExtended           Extended-type precision
                                    pmReserved           ?
                                    pmSingle             Single-type precision

                   Table 17.12:  Enumeration values for type TFPURoundingMode


                     __Value______________Explanation_____________________________________________________
                       rmDown              Round to biggest integer smaller than value.
                       rmNearest           Round to nearest integer value
                       rmTruncate          Cut off fractional part.
                       rmUp                Round to smallest integer larger than value.

Type describing the default precision for the Floating Point processor.


TFPURoundingMode  =  (rmNearest,rmDown,rmUp,rmTruncate)


Type describing the rounding mode for the Floating Point processor.


tpaymenttime  =  (ptendofperiod,ptstartofperiod)
                        Table 17.13:  Enumeration values for type tpaymenttime


                                      __Value____________________Explanation____________
                                        ptendofperiod            End of period.
                                        ptstartofperiod          Start of period.
Type used in financial (interest) calculations.


TRoundToRange  =  -37..37


TRoundToRange is the range of valid digits to be used in the RoundTo (722  ) function.


TValueRelationship  =  -1..1


Type to describe relational order between values


TValueSign  =  -1..1


Type indicating sign of a valuea

                                                                 693

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12            Procedures  and  functions



                17.12.1          arccos

    Synopsis:    Return inverse cosine

Declaration:     function  arccos(x:  float)  :  float

    Visibility:   default

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 (695  ), arcosh (695  ), arsinh (697  ), artanh (697  )


                Listing:  ./mathex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  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   ;


                    P r o c e d u r eWriteRadDeg         (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 e g(x ) : 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.2          arccosh

    Synopsis:    Return inverse hyperbolic cosine

Declaration:     function  arccosh(x:  float)  :  float

    Visibility:   default

Description:     arccosh returns the inverse hyperbolic cosine of it's argument x.

                This function is an alias for arcosh (695  ), provided for Delphi compatibility.

    See also:    arcosh (695  )

                                                                                 694

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.3          arcosh

    Synopsis:    Return inverse hyperbolic cosine

Declaration:     function  arcosh(x:  float)  :  float

    Visibility:   default

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 Delphi compatibility.

       Errors:   If the argument x is not in the allowed range, an EInvalidArgument exception is raised.

    See also:    cosh (699  ), sinh (725  ), arcsin (695  ), arsinh (697  ), artanh (697  ), tanh (730  )


                Listing:  ./mathex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.4          arcsin

    Synopsis:    Return inverse sine

Declaration:     function  arcsin(x:  float)  :  float

    Visibility:   default

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 (694  ), arcosh (695  ), arsinh (697  ), artanh (697  )


                Listing:  ./mathex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  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   ;


                    P r o c e d u r eWriteRadDeg         (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 e g(x ) : 8 : 5 ,'  d e g r e e s.')
                    end  ;


                 b e g i n
                    WriteRadDeg          ( a r c s i n( 1 ) ) ;



                                                                                 695

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                    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___.____________________________________________________________________________________________________________*
 *___________

                17.12.5          arcsinh

    Synopsis:    Return inverse hyperbolic sine

Declaration:     function  arcsinh(x:  float)  :  float

    Visibility:   default

Description:     arcsinh returns the inverse hyperbolic sine of it's argument x.

                This function is an alias for arsinh (697  ), provided for Delphi compatibility.

    See also:    arsinh (697  )
                17.12.6          arctan2

    Synopsis:    Return arctangent of (y/x)

Declaration:     function  arctan2(y:  float;x:  float)  :  float

    Visibility:   default

Description:     arctan2  calculates  arctan(y/x),  and  returns  an  angle  in  the  correct  quadrant.  The  re-
                turned angle will be in the range $-\pi$ to $\pi$ 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 (694  ), arcosh (695  ), arsinh (697  ), artanh (697  )


                Listing:  ./mathex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  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   ;


                    P r o c e d u r eWriteRadDeg         (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 e g(x ) : 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___.____________________________________________________________________________________________________________*
 *___________
                                                                                 696

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.7          arctanh

    Synopsis:    Return inverse hyperbolic tangent

Declaration:     function  arctanh(x:  float)  :  float

    Visibility:   default

Description:     arcsinh returns the inverse hyperbolic tangent of it's argument x.

                This function is an alias for artanh (697  ), provided for Delphi compatibility.

    See also:    artanh (697  )
                17.12.8          arsinh

    Synopsis:    Return inverse hyperbolic sine

Declaration:     function  arsinh(x:  float)  :  float

    Visibility:   default

Description:     arsinh returns the inverse hyperbolic sine of its argument x.  The arscsinh variant of this
                function is supplied for Delphi compatibility.

       Errors:   None.

    See also:    arcosh (695  ), arccos (694  ), arcsin (695  ), artanh (697  )


                Listing:  ./mathex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.9          artanh

    Synopsis:    Return inverse hyperbolic tangent

Declaration:     function  artanh(x:  float)  :  float

    Visibility:   default

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 Delphi
                compatibility.

       Errors:   In case x is not in the interval [-1,1], an EInvalidArgument exception is raised.

    See also:    arcosh (695  ), arccos (694  ), arcsin (695  ), artanh (697  )


                Listing:  ./mathex/ex5.pp



                                                                                 697

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.10           ceil

    Synopsis:    Return the lowest integer number greater than or equal to argument

Declaration:     function  ceil(x:  float)  :  Integer

    Visibility:   default

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 (703  )


                Listing:  ./mathex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.11           ClearExceptions

    Synopsis:    Clear Floating Point Unit exceptions

Declaration:     procedure  ClearExceptions(RaisePending:  Boolean)

    Visibility:   default

Description:     Clear Floating Point Unit exceptions
                17.12.12           CompareValue

    Synopsis:    Compare 2 values


                                                                                 698

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
Declaration:     function  CompareValue(const  A:  Integer;const  B:  Integer)
                                                    :  TValueRelationship
                function  CompareValue(const  A:  Int64;const  B:  Int64)
                                                    :  TValueRelationship
                function  CompareValue(const  A:  QWord;const  B:  QWord)
                                                    :  TValueRelationship
                function  CompareValue(const  A:  Extended;const  B:  Extended;
                                                  delta:  Extended)  :  TValueRelationship

    Visibility:  default

Description:     CompareValue compares 2 integer or floating point values A and B and returns one of the
                following values:

                -1 if  A<B

                0if  A=B

                -1 if  A>B

    See also:    TValueRelationship (693  )
                17.12.13           cosecant

    Synopsis:    Calculate cosecant

Declaration:     function  cosecant(x:  float)  :  float

    Visibility:   default

Description:     cosecant calculates the cosecant (1/sin(x)) of its argument x.

       Errors:   If 0 or 180 degrees is specified, an exception will be raised.

    See also:    secant (723  )
                17.12.14           cosh

    Synopsis:    Return hyperbolic cosine

Declaration:     function  cosh(x:  float)  :  float

    Visibility:   default

Description:     Cosh returns the hyperbolic cosine of it's argument {x}.

       Errors:   None.

    See also:    arcosh (695  ), sinh (725  ), arsinh (697  )


                Listing:__./mathex/ex8.pp__________________________________________________________________________________________*
 *___________

                Program       Example8       ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________
                                                                                 699

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.15           cot

    Synopsis:    Alias for Cotan

Declaration:     function  cot(x:  float)  :  float

    Visibility:   default

Description:     cot is an alias for the cotan (700  ) function.

    See also:    cotan (700  )
                17.12.16           cotan

    Synopsis:    Return cotangent

Declaration:     function  cotan(x:  float)  :  float

    Visibility:   default

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 (730  )


                Listing:  ./mathex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.17           csc

    Synopsis:    Alias for cosecant

Declaration:     function  csc(x:  float)  :  float

    Visibility:   default

Description:     csc is an alias for the cosecant (699  ) function.

    See also:    cosecant (699  )
                                                                                 700

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.18           cycletorad

    Synopsis:    Convert cycle angle to radians angle

Declaration:     function  cycletorad(cycle:  float)  :  float

    Visibility:   default

Description:     Cycletorad transforms it's argument cycle (an angle expressed in cycles) to radians.  (1
                cycle is $2 \pi$ radians).

       Errors:   None.

    See also:    degtograd (701  ), degtorad (702  ), radtodeg (721  ), radtograd (721  ), radtocycle (720  )


                Listing:  ./mathex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                {   Program       t o  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(c o s( 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(c o s( 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.19           degtograd

    Synopsis:    Convert degree angle to grads angle

Declaration:     function  degtograd(deg:  float)  :  float

    Visibility:   default

Description:     Degtograd transforms it's argument deg (an angle in degrees) to grads.  (90 degrees is 100
                grad.)

       Errors:   None.

    See also:    cycletorad (701  ), degtorad (702  ), radtodeg (721  ), radtograd (721  ), radtocycle (720  )


                Listing:  ./mathex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________
                                                                                 701

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.20           degtorad

    Synopsis:    Convert degree angle to radians angle.

Declaration:     function  degtorad(deg:  float)  :  float

    Visibility:   default

Description:     Degtorad  converts  it's  argument  deg  (an  angle  in  degrees)  to  radians.  (pi  radians  is  180
                degrees)

       Errors:   None.

    See also:    cycletorad (701  ), degtograd (701  ), radtodeg (721  ), radtograd (721  ), radtocycle (720  )


                Listing:__./mathex/ex12.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 2;


                {   Program       t o  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   ;


                 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.21           DivMod

    Synopsis:    Return DIV and MOD of arguments

Declaration:     procedure  DivMod(Dividend:  Integer;Divisor:  Word;var  Result:  Word;
                                           var  Remainder:  Word)
                procedure  DivMod(Dividend:  Integer;Divisor:  Word;var  Result:  SmallInt;
                                           var  Remainder:  SmallInt)

    Visibility:   default

Description:     DivMod returns Dividend DIV Divisor in Result, and Dividend MOD Divisor in Remainder
                17.12.22           EnsureRange

    Synopsis:    Change value to it falls in specified range.

Declaration:     function  EnsureRange(const  AValue:  Integer;const  AMin:  Integer;
                                                 const  AMax:  Integer)  :  Integer
                function  EnsureRange(const  AValue:  Int64;const  AMin:  Int64;
                                                 const  AMax:  Int64)  :  Int64

    Visibility:   default

Description:     EnsureRange  returns  Value  if  AValue  is  in  the  range  AMin..AMax.  It  returns  AMin  if  the
                value is less than AMin, or AMax if the value is larger than AMax.

    See also:    InRange (706  )



                                                                                 702

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.23           floor

    Synopsis:    Return the largest integer smaller than or equal to argument

Declaration:     function  floor(x:  float)  :  Integer

    Visibility:   default

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 (698  )


                Listing:  ./mathex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.24           Frexp

    Synopsis:    Return mantissa and exponent.

Declaration:     procedure  Frexp(X:  float;var  Mantissa:  float;var  Exponent:  Integer)

    Visibility:   default

Description:     Frexp returns the mantissa and exponent of it's argument x in mantissa and exponent.

       Errors:   None


                Listing:  ./mathex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                {   Program       t o  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   ;


                 P r o c e d u r ed 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   :  l o n g i n t;


                 b e g i n
                    man  : = 0 ;
                    exp  : = 0 ;
                    f r e x p(x , man  , exp  ) ;
                    w r i t e(x , '  h a s   ') ;



                                                                                 703

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                    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___.____________________________________________________________________________________________________________*
 *___________

                17.12.25           GetExceptionMask

    Synopsis:    Get the Floating Point Unit exception mask.

Declaration:     function  GetExceptionMask  :  TFPUExceptionMask

    Visibility:   default

Description:     Get the Floating Point Unit exception mask.
                17.12.26           GetPrecisionMode

    Synopsis:    Return the Floating Point Unit precision mode.

Declaration:     function  GetPrecisionMode  :  TFPUPrecisionMode

    Visibility:   default

Description:     Return the Floating Point Unit precision mode.
                17.12.27           GetRoundMode

    Synopsis:    Return the Floating Point Unit rounding mode.

Declaration:     function  GetRoundMode  :  TFPURoundingMode

    Visibility:   default

Description:     Return the Floating Point Unit rounding mode.
                17.12.28           gradtodeg

    Synopsis:    Convert grads angle to degrees angle

Declaration:     function  gradtodeg(grad:  float)  :  float

    Visibility:   default

Description:     Gradtodeg  converts  its  argument  grad  (an  angle  in  grads)  to  degrees.   (100  grad  is  90
                degrees)

       Errors:   None.

    See also:    cycletorad (701  ), degtograd (701  ), radtodeg (721  ), radtograd (721  ), radtocycle (720  ), grad-
                torad (705  )



                                                                                 704

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                Listing:  ./mathex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.29           gradtorad

    Synopsis:    Convert grads angle to radians angle

Declaration:     function  gradtorad(grad:  float)  :  float

    Visibility:   default

Description:     Gradtorad  converts  its  argument  grad  (an  angle  in  grads)  to  radians.   (200  grad  is  pi
                degrees).

       Errors:   None.

    See also:    cycletorad (701  ), degtograd (701  ), radtodeg (721  ), radtograd (721  ), radtocycle (720  ), grad-
                todeg (704  )


                Listing:  ./mathex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.30           hypot

    Synopsis:    Return hypotenuse of triangle

Declaration:     function  hypot(x:  float;y:  float)  :  float

    Visibility:   default

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.

                                                                                 705

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                Listing:  ./mathex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.31           ifthen

    Synopsis:    Return one of two values, depending on a boolean condition

Declaration:     function  ifthen(val:  Boolean;const  iftrue:  Integer;
                                         const  iffalse:  Integer)  :  Integer
                function  ifthen(val:  Boolean;const  iftrue:  Int64;const  iffalse:  Int64)
                                           :  Int64
                function  ifthen(val:  Boolean;const  iftrue:  double;const  iffalse:  double)
                                           :  double
                function  ifthen(val:  Boolean;const  iftrue:  String;const  iffalse:  String)
                                           :  String

    Visibility:   default

Description:     ifthen returns iftrue if  val is True, and False if  val is False.

                This function can be used in expressions.
                17.12.32           InRange

    Synopsis:    Check whether value is in range.

Declaration:     function  InRange(const  AValue:  Integer;const  AMin:  Integer;
                                           const  AMax:  Integer)  :  Boolean
                function  InRange(const  AValue:  Int64;const  AMin:  Int64;
                                           const  AMax:  Int64)  :  Boolean

    Visibility:   default

Description:     InRange returns True if  AValue is in the range AMin..AMax.  It returns False if  Value lies
                outside the specified range.

    See also:    EnsureRange (702  )
                17.12.33           intpower

    Synopsis:    Return integer power.

Declaration:     function  intpower(base:  float;const  exponent:  Integer)  :  float

    Visibility:   default

Description:     Intpower returns base to the power exponent, where exponent is an integer value.

                                                                                 706

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
       Errors:   If  base is zero and the exponent is negative, then an overflow error will occur.

    See also:    power (720  )


                Listing:  ./mathex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  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   ;


                 P r o c e d u r eD 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 r(X ,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___.____________________________________________________________________________________________________________*
 *___________

                17.12.34           IsInfinite

    Synopsis:    Check whether value is infinite

Declaration:     function  IsInfinite(const  d:  Double)  :  Boolean

    Visibility:   default

Description:     IsInfinite returns True if the double d contains the infinite value.

    See also:    IsZero (708  ), IsInfinite (707  )
                17.12.35           IsNan

    Synopsis:    Check whether value is Not a Number

Declaration:     function  IsNan(const  d:  Double)  :  Boolean

    Visibility:   default

Description:     IsNan  returns  True  if  the  double  d  contains  Not  A  Number  (a  value  which  cannot  be
                represented correctly in double format).

    See also:    IsZero (708  ), IsInfinite (707  )


                                                                                 707

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.36           IsZero

    Synopsis:    Check whether value is zero

Declaration:     function  IsZero(const  A:  Single;Epsilon:  Single)  :  Boolean
                function  IsZero(const  A:  Single)  :  Boolean
                function  IsZero(const  A:  Extended;Epsilon:  Extended)  :  Boolean
                function  IsZero(const  A:  Extended)  :  Boolean

    Visibility:   default

Description:     IsZero checks whether the float value A is zero,  up to a precision of  Epsilon.  It returns
                True if Abs(A) is less than Epsilon.

                The default value for Epsilon is dependent on the type of the arguments, but is MinFloat
                (691  ) for the float type.

    See also:    IsNan (707  ), IsInfinite (707  ), SameValue (723  )
                17.12.37           ldexp

    Synopsis:    Return (2 to the power p) times x

Declaration:     function  ldexp(x:  float;const  p:  Integer)  :  float

    Visibility:   default

Description:     Ldexp returns (2 to the power p) times x.

       Errors:   None.

    See also:    lnxp1 (708  ), log10 (709  ), log2 (709  ), logn (710  )


                Listing:  ./mathex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 9;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.38           lnxp1

    Synopsis:    Return natural logarithm of 1+X

Declaration:     function  lnxp1(x:  float)  :  float

    Visibility:   default

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\leq -1$ then an EInvalidArgument exception will be raised.
                                                                                 708

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
    See also:    ldexp (708  ), log10 (709  ), log2 (709  ), logn (710  )


                Listing:  ./mathex/ex20.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 0;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.39           log10

    Synopsis:    Return 10-Based logarithm.

Declaration:     function  log10(x:  float)  :  float

    Visibility:   default

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 (708  ), lnxp1 (708  ), log2 (709  ), logn (710  )


                Listing:  ./mathex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 1;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.40           log2

    Synopsis:    Return 2-based logarithm

Declaration:     function  log2(x:  float)  :  float

    Visibility:   default

Description:     Log2 returns the 2-base logarithm of  X.



                                                                                 709

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
       Errors:   If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.

    See also:    ldexp (708  ), lnxp1 (708  ), log10 (709  ), logn (710  )


                Listing:  ./mathex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   Program       t o  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   ;


                 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.41           logn

    Synopsis:    Return N-based logarithm.

Declaration:     function  logn(n:  float;x:  float)  :  float

    Visibility:   default

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 (708  ), lnxp1 (708  ), log10 (709  ), log2 (709  )


                Listing:  ./mathex/ex23.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 3;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 710

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.42           Max

    Synopsis:    Return largest of 2 values

Declaration:     function  Max(a:  Integer;b:  Integer)  :  Integer
                function  Max(a:  Int64;b:  Int64)  :  Int64
                function  Max(a:  Extended;b:  Extended)  :  Extended

    Visibility:   default

Description:     Max returns the maximum of  Int1 and Int2.

       Errors:   None.

    See also:    min (714  ), maxIntValue (711  ), maxvalue (712  )


                Listing:  ./mathex/ex24.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 4;


                {   Program       t o  d e m o n s t r a t et h e  max    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(max  ( a ,b ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.43           MaxIntValue

    Synopsis:    Return largest element in integer array

Declaration:     function  MaxIntValue(const  Data:  Array  of  Integer)  :  Integer

    Visibility:   default

Description:     MaxIntValue returns the largest integer out of the Data array.

                This function is provided for Delphi compatibility, use the maxvalue (712  ) function instead.

       Errors:   None.

    See also:    maxvalue (712  ), minvalue (716  ), minIntValue (715  )


                Listing:  ./mathex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   Program       t o  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



                                                                                 711

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  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 := low  ( e x a r r a y)  t o  h i g h( e x a r r a y) 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.44           maxvalue

    Synopsis:    Return largest value in array

Declaration:     function  maxvalue(const  data:  Array  of  Extended)  :  Extended
                function  maxvalue(const  data:  PExtended;const  N:  Integer)  :  Extended
                function  maxvalue(const  data:  Array  of  Integer)  :  Integer
                function  maxvalue(const  data:  PInteger;const  N:  Integer)  :  Integer

    Visibility:   default

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.

    See also:    maxIntValue (711  ), minvalue (716  ), minIntValue (715  )


                Listing:  ./mathex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 2 6;


                {   Program       t o  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}


                 u s e s math   ;


                 v a r  i : 1 . . 1 0 0 ;
                        f _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  F l o a t;
                        i _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  I n t e g e r;
                        P f _a r r a y:P f l o a t;
                        P I _a r r a y:P i n t e g e r;


                 b e g i n
                    randomize       ;


                    P f _a r r a y:=  @ f _a r r a y[ 1 ] ;
                    P i _a r r a y:=  @ i _a r r a y[ 1 ] ;


                    f o r  i := low  ( f _a r r a y )  t o  h i g h( f _a r r a y)  do
                        f _a r r a y[ i] : = (random    - random     ) * 1 0 0 ;



                                                                                 712

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                    f o r  i := low  ( i _a r r a y )  t o  h i g h( i _a r r a y)  do
                        i _a r r a y[ i] : =random     ( I)-  random    ( 1 0 0 ) ;


                    W r i t e l n('Max     F l o a t            :  ' ,MaxValue       (f _a r r a y ) : 8 : 4 ) ;
                    W r i t e l n('Max     F l o a t     (b )  :   ' ,MaxValue       (P f _a r r a y, 1 0 0 ) : 8 : 4 ) ;
                    W r i t e l n('Max     I n t e g e r        :  ' ,MaxValue       ( i _a r r a y) : 8 ) ;
                    W r i t e l n('Max     I n t e g e r( b )  :   ' ,MaxValue       (P i _a r r a y, 1 0 0 ) : 8 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.45           mean

    Synopsis:    Return mean value of array

Declaration:     function  mean(const  data:  Array  of  Extended)  :  float
                function  mean(const  data:  PExtended;const  N:  LongInt)  :  float

    Visibility:   default

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 (713  ), momentskewkurtosis (716  ), sum (727  )


                Listing:  ./mathex/ex27.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 7;


                {   Program       t o  d e m o n s t r a t et h e  Mean     f u n c t i o n. }


                Uses     math   ;


                Type
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  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 := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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             :  ' ,M i n V a l u e(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   ( @ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.46           meanandstddev

    Synopsis:    Return mean and standard deviation of array

Declaration:     procedure  meanandstddev(const  data:  Array  of  Extended;var  mean:  float;
                                                      var  stddev:  float)



                                                                                 713

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                procedure  meanandstddev(const  data:  PExtended;const  N:  LongInt;
                                                     var  mean:  float;var  stddev:  float)

    Visibility:  default

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 (713  ), sum (727  ), sumofsquares (727  ), momentskewkurtosis (716  )


                Listing:  ./mathex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 8;


                {   Program       t o  d e m o n s t r a t et h e  M e a n a n d s t d d e vf u n c t i o n. }


                Uses     math   ;


                Type
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  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 := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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          (@ E x A r r a y[ 1 ] , 1 0 0M,ean  , StdDev     ) ;
                    W r i t e l n('Mean         (b  )  :   ', Mean   : 8 : 4 ) ;
                    W r i t e l n(' StdDev      (b  )  :   ', StdDev     : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.47           Min

    Synopsis:    Return smallest of two values.

Declaration:     function  Min(a:  Integer;b:  Integer)  :  Integer
                function  Min(a:  Int64;b:  Int64)  :  Int64
                function  Min(a:  Extended;b:  Extended)  :  Extended

    Visibility:   default

Description:     min returns the smallest value of  Int1 and Int2;

       Errors:   None.

    See also:    max (711  )


                Listing:  ./mathex/ex29.pp



                                                                                 714

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 9;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.48           MinIntValue

    Synopsis:    Return smallest value in integer array

Declaration:     function  MinIntValue(const  Data:  Array  of  Integer)  :  Integer

    Visibility:   default

Description:     MinIntvalue returns the smallest value in the Data array.

                This function is provided for Delphi compatibility, use minvalue instead.

       Errors:   None

    See also:    minvalue (716  ), maxIntValue (711  ), maxvalue (712  )


                Listing:  ./mathex/ex30.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 0;


                {   Program       t o  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       =   A r r a y[ 1 . . 1 0 0 ] o f  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 := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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___.____________________________________________________________________________________________________________*
 *___________

                                                                                 715

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.49           minvalue

    Synopsis:    Return smallest value in array

Declaration:     function  minvalue(const  data:  Array  of  Extended)  :  Extended
                function  minvalue(const  data:  PExtended;const  N:  Integer)  :  Extended
                function  minvalue(const  data:  Array  of  Integer)  :  Integer
                function  MinValue(const  Data:  PInteger;const  N:  Integer)  :  Integer

    Visibility:   default

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 (711  ), maxvalue (712  ), minIntValue (715  )


                Listing:  ./mathex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  M i n V a l u e f u n c t i o n. }


                {   Make     s u r e  i n t e g e r i s 3 2   b i t}
                { $mode      o b j f p c}


                 u s e s math   ;


                 v a r  i : 1 . . 1 0 0 ;
                        f _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  F l o a t;
                        i _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  I n t e g e r;
                        P f _a r r a y:P f l o a t;
                        P I _a r r a y:P i n t e g e r;


                 b e g i n
                    randomize       ;


                    P f _a r r a y:=  @ f _a r r a y[ 1 ] ;
                    P i _a r r a y:=  @ i _a r r a y[ 1 ] ;


                    f o r  i := low  ( f _a r r a y )  t o  h i g h( f _a r r a y)  do
                        f _a r r a y[ i] : = (random    - random     ) * 1 0 0 ;
                    f o r  i := low  ( i _a r r a y )  t o  h i g h( i _a r r a y)  do
                        i _a r r a y[ i] : =random     ( I)-  random    ( 1 0 0 ) ;


                    W r i t e l n(' Min    F l o a t            :  ' , M i n V a l u e(f _a r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Min    F l o a t     (b )  :   ' , M i n V a l u e(P f _a r r a y, 1 0 0 ) : 8 : 4 ) ;
                    W r i t e l n(' Min    I n t e g e r        :  ' , M i n V a l u e(i _a r r a y) : 8 ) ;
                    W r i t e l n(' Min    I n t e g e r( b )  :   ' , M i n V a l u e(P i _a r r a y, 1 0 0 ) : 8 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.50           momentskewkurtosis

    Synopsis:    Return 4 first moments of distribution

                                                                                 716

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
Declaration:     procedure  momentskewkurtosis(const  data:  Array  of  Extended;
                                                              out  m1:  float;out  m2:  float;out  m3:  float;
                                                              out  m4:  float;out  skew:  float;
                                                              out  kurtosis:  float)
                procedure  momentskewkurtosis(const  data:  PExtended;const  N:  Integer;
                                                              out  m1:  float;out  m2:  float;out  m3:  float;
                                                              out  m4:  float;out  skew:  float;
                                                              out  kurtosis:  float)

    Visibility:  default

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 (713  ), meanandstddev (713  )


                Listing:  ./mathex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 2;


                {   Program       t o  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 ifsu n c t i o n. }


                 u s e s math   ;


                 v a r  d i s t a r r a:ya r r a y[ 1 . . 1 0 0 0 ]o f   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 := low  ( d i s t a r r a y) t o   h i g h( d i s t a r r a)y 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(iDsi s t A r r a y,m1 ,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 ( '2 nd   moment       :  ' ,m2  : 8 : 6 ) ;
                    W r i t e l n ( '3 r d  moment       :  ' ,m3  : 8 : 6 ) ;
                    W r i t e l n ( '4 t h  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 i s: 8 : 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.51           norm

    Synopsis:    Return Euclidian norm

Declaration:     function  norm(const  data:  Array  of  Extended)  :  float
                function  norm(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

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.



                                                                                 717

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
    See also:    sumofsquares (727  )


                Listing:  ./mathex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  norm     f u n c t i o n. }


                 u s e s math   ;


                 v a r v : a r r a y[ 1 . . 1 0 ] o f  F l o a t;
                        I : 1 . . 1 0 ;


                 b e g i n
                    f o r  I := low  ( v )  t o   h i g h(v )  do
                       v [ i ] : =random     ;
                    w r i t e l n(norm   ( v ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.52           operator  **(float,  float):  float

Declaration:     function  operator  **(float,  float):  float(bas:  float;expo:  float)
                                                                                     :  float

    Visibility:   default
                17.12.53           operator  **(Int64,  Int64):  Int64

Declaration:     function  operator  **(Int64,  Int64):  Int64(bas:  Int64;expo:  Int64)
                                                                                     :  Int64

    Visibility:   default
                17.12.54           popnstddev

    Synopsis:    Return population variance

Declaration:     function  popnstddev(const  data:  Array  of  Extended)  :  float
                function  popnstddev(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

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 (719  ), mean (713  ), meanandstddev (713  ), stddev (726  ), momentskewkurtosis
                (716  )


                Listing:  ./mathex/ex35.pp
                                                                                 718

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   Program       t o  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       =   A r r a y[ 1 . . 1 0 0 ] o f  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 := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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                           :  ' ,M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    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        (@ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4 )*
 * ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.55           popnvariance

    Synopsis:    Return population variance

Declaration:     function  popnvariance(const  data:  PExtended;const  N:  Integer)  :  float
                function  popnvariance(const  data:  Array  of  Extended)  :  float

    Visibility:   default

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  (718  ),  mean  (713  ),  meanandstddev  (713  ),  stddev  (726  ),  momentskewkurtosis
                (716  )


                Listing:  ./mathex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  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   ;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) do
                        E x A r r a y[i] : = (Random    - Random     ) * 1 0 0 ;



                                                                                 719

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                    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                     :   ' ,M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Pop  .   v a r.         :   ' ,P o p n V a r i a n c(eE x A r 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(e@ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.56           power

    Synopsis:    Return real power.

Declaration:     function  power(base:  float;exponent:  float)  :  float

    Visibility:   default

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 (706  )


                Listing:  ./mathex/ex34.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 4;


                {   Program       t o  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 ed o p o w e r(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
                    d o p o w e r( 2 , 2 ) ;
                    d o p o w e r( 2 , - 2 ) ;
                    d o p o w e r( 2 , 0 . 0 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.57           radtocycle

    Synopsis:    Convert radians angle to cycle angle

Declaration:     function  radtocycle(rad:  float)  :  float

    Visibility:   default

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 (701  ), degtorad (702  ), radtodeg (721  ), radtograd (721  ), cycletorad (701  )


                Listing:  ./mathex/ex37.pp



                                                                                 720

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   Program       t o  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(e2 * p i) : 8 : 6 ) ;
                    w r i t e l n(r a d t o c y c l(ep i ) : 8 : 6 ) ;
                    w r i t e l n(r a d t o c y c l(ep i / 2 ) : 8 : 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.58           radtodeg

    Synopsis:    Convert radians angle to degrees angle

Declaration:     function  radtodeg(rad:  float)  :  float

    Visibility:   default

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 (701  ), degtorad (702  ), radtocycle (720  ), radtograd (721  ), cycletorad (701  )


                Listing:  ./mathex/ex38.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.59           radtograd

    Synopsis:    Convert radians angle to grads angle

Declaration:     function  radtograd(rad:  float)  :  float

    Visibility:   default

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 (701  ), degtorad (702  ), radtocycle (720  ), radtodeg (721  ), cycletorad (701  )
                                                                                 721

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                Listing:  ./mathex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.60           randg

    Synopsis:    Return gaussian distributed random number.

Declaration:     function  randg(mean:  float;stddev:  float)  :  float

    Visibility:   default

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 (713  ), stddev (726  ), meanandstddev (713  )


                Listing:  ./mathex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 0;


                {   Program       t o  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   ;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 0 0 ]o f   F l o a t; ;
                    Mean   , s t d d e v :   F l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.61           RoundTo

    Synopsis:    Round to the specified number of digits

Declaration:     function  RoundTo(const  AVAlue:  Extended;const  Digits:  TRoundToRange)
                                            :  Extended



                                                                                 722

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
    Visibility:  default

Description:     RoundTo  rounds  the  specified  float  AVAlue  to  the  specified  number  of  digits  and  returns
                the result.  This result is accurate to "10 to the power Digits".  It uses the standard Round
                function for this.

    See also:    TRoundToRange (693  ), SimpleRoundTo (724  )
                17.12.62           SameValue

    Synopsis:    Check whether 2 float values are the same

Declaration:     function  SameValue(const  A:  Extended;const  B:  Extended)  :  Boolean
                function  SameValue(const  A:  Single;const  B:  Single)  :  Boolean
                function  SameValue(const  A:  Extended;const  B:  Extended;
                                              Epsilon:  Extended)  :  Boolean
                function  SameValue(const  A:  Single;const  B:  Single;Epsilon:  Single)
                                                :  Boolean

    Visibility:   default

Description:     SameValue returns True if the floating-point values A and B are the same, i.e.  whether the
                absolute value of their their difference is smaller than Epsilon.  If their difference is larger,
                then False is returned.

                The default value for Epsilon is dependent on the type of the arguments, but is MinFloat
                (691  ) for the float type.

    See also:    MinFloat (691  ), IsZero (708  )
                17.12.63           sec

    Synopsis:    Alias for secant

Declaration:     function  sec(x:  float)  :  float

    Visibility:   default

Description:     sec is an alias for the secant (723  ) function.

    See also:    secant (723  )
                17.12.64           secant

    Synopsis:    Calculate secant

Declaration:     function  secant(x:  float)  :  float

    Visibility:   default

Description:     Secant calculates the secant (1/cos(x)) of its argument x.

       Errors:   If 90 or 270 degrees is specified, an exception will be raised.

    See also:    cosecant (699  )

                                                                                 723

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.65           SetExceptionMask

    Synopsis:    Set the Floating Point Unit exception mask.

Declaration:     function  SetExceptionMask(const  Mask:  TFPUExceptionMask)
                                                           :  TFPUExceptionMask

    Visibility:   default

Description:     Set the Floating Point Unit exception mask.
                17.12.66           SetPrecisionMode

    Synopsis:    Set the Floating Point Unit precision mode.

Declaration:     function  SetPrecisionMode(const  Precision:  TFPUPrecisionMode)
                                                           :  TFPUPrecisionMode

    Visibility:   default

Description:     Set the Floating Point Unit precision mode.
                17.12.67           SetRoundMode

    Synopsis:    Set the Floating Point Unit rounding mode.

Declaration:     function  SetRoundMode(const  RoundMode:  TFPURoundingMode)
                                                     :  TFPURoundingMode

    Visibility:   default

Description:     Set the Floating Point Unit rounding mode.
                17.12.68           Sign

    Synopsis:    Return sign of argument

Declaration:     function  Sign(const  AValue:  Integer)  :  TValueSign
                function  Sign(const  AValue:  Int64)  :  TValueSign
                function  Sign(const  AValue:  Double)  :  TValueSign
                function  Sign(const  AValue:  Extended)  :  TValueSign

    Visibility:   default

Description:     Sign returns the sign of it's argument, which can be an Integer, 64 bit integer, or a double.
                The returned value is an integer which is -1, 0 or 1, and can be used to do further calculations
                with.
                17.12.69           SimpleRoundTo

    Synopsis:    Round to the specified number of digits (rounding up if needed)

Declaration:     function  SimpleRoundTo(const  AValue:  Extended;
                                                     const  Digits:  TRoundToRange)  :  Extended

    Visibility:   default

                                                                                 724

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
Description:     SimplRoundTo rounds the specified float AVAlue to the specified number of digits, but rounds
                up, and returns the result.  This result is accurate to "10 to the power Digits".  It uses the
                standard Round function for this.

    See also:    TRoundToRange (693  ), RoundTo (722  )
                17.12.70           sincos

    Synopsis:    Return sine and cosine of argument

Declaration:     procedure  sincos(theta:  float;out  sinus:  float;out  cosinus:  float)

    Visibility:   default

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 calculate the sine
                and cosine separately.

       Errors:   None.

    See also:    arcsin (695  ), arccos (694  )


                Listing:  ./mathex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 1;


                {   Program       t o  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   ;


                 P r o c e d u r ed 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 e: 8 : 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.71           sinh

    Synopsis:    Return hyperbolic sine

Declaration:     function  sinh(x:  float)  :  float
                                                                                 725

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
    Visibility:  default

Description:     Sinh returns the hyperbolic sine of its argument x.

       Errors:

    See also:    cosh (699  ), arsinh (697  ), tanh (730  ), artanh (697  )


                Listing:__./mathex/ex42.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 4 2;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________

                17.12.72           stddev

    Synopsis:    Return standard deviation of data

Declaration:     function  stddev(const  data:  Array  of  Extended)  :  float
                function  stddev(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

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 (713  ), meanandstddev (713  ), variance (731  ), totalvariance (730  )


                Listing:__./mathex/ex43.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 4 0;


                {   Program       t o  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   ;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 0 0 ]o f   F l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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    ( @ E x A r r a y[ 0 ] , 1 0 0 0 0 ) : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                 726

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.73           sum

    Synopsis:    Return sum of values

Declaration:     function  sum(const  data:  Array  of  Extended)  :  float
                function  sum(const  data:  PExtended;const  N:  LongInt)  :  float

    Visibility:   default

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 (727  ), sumsandsquares (728  ), totalvariance (730  ), variance (731  )


                Listing:  ./mathex/ex44.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 4;


                {   Program       t o  d e m o n s t r a t et h e  Sum    f u n c t i o n. }


                Uses     math   ;


                Var
                    I   :  1 . . 1 0 0 ;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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           :  ' , M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n('Sum            :  ' ,Sum   ( E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n('Sum     (b )  :   ' ,Sum   ( @ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.74           sumInt

    Synopsis:    Return the sum of an array of integers

Declaration:     function  sumInt(const  data:  PInt64;const  N:  LongInt)  :  Int64
                function  sumInt(const  data:  Array  of  Int64)  :  Int64

    Visibility:   default

Description:     SumInt returns the sum of the N integers in the Data array, where this can be an open array
                or a pointer to an array.

       Errors:   An overflow may occur.
                17.12.75           sumofsquares

    Synopsis:    Return sum of squares of values

Declaration:     function  sumofsquares(const  data:  Array  of  Extended)  :  float
                function  sumofsquares(const  data:  PExtended;const  N:  Integer)  :  float



                                                                                 727

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
    Visibility:  default

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 (727  ), sumsandsquares (728  ), totalvariance (730  ), variance (731  )


                Listing:  ./mathex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  SumOfSquares           f u n c t i o n. }


                Uses     math   ;


                Var
                    I   :  1 . . 1 0 0 ;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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                         :  ' , M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    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        ( @ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4*
 * ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.12.76           sumsandsquares

    Synopsis:    Return sum and sum of squares of values.

Declaration:     procedure  sumsandsquares(const  data:  Array  of  Extended;var  sum:  float;
                                                        var  sumofsquares:  float)
                procedure  sumsandsquares(const  data:  PExtended;const  N:  Integer;
                                                        var  sum:  float;var  sumofsquares:  float)

    Visibility:   default

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 (727  ), sumofsquares (727  ), totalvariance (730  ), variance (731  )


                Listing:  ./mathex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  SumOfSquares           f u n c t i o n. }


                Uses     math   ;



                                                                                 728

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________


                Var
                    I   :  1 . . 1 0 0 ;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t
                    s , s s  :  f l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) 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                         :  ' , M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    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          ( @ E x A r r a y[ 1 ] , 1 0 0S,,SS  ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                17.12.77           tan

    Synopsis:    Return tangent

Declaration:     function  tan(x:  float)  :  float

    Visibility:   default

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 (730  ), arcsin (695  ), sincos (725  ), arccos (694  )


                Listing:  ./mathex/ex47.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   Program       t o  d e m o n s t r a t et h e  Tan    f u n c t i o n. }


                Uses     math   ;


                 P r o c e d u r eDoTan    (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('  T a n g e n t  :  ' ,Tan   (A n g l e) : 8 : 6 ) ;
                end   ;


                 b e g i n
                    DoTan    ( 0 ) ;
                    DoTan    (P i ) ;
                    DoTan    (P i / 3 ) ;
                    DoTAn    (P i / 4 ) ;
                    DoTan    (P i / 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                 729

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                17.12.78           tanh

    Synopsis:    Return hyperbolic tangent

Declaration:     function  tanh(x:  float)  :  float

    Visibility:   default

Description:     Tanh returns the hyperbolic tangent of  x.

       Errors:   None.

    See also:    arcsin (695  ), sincos (725  ), arccos (694  )


                Listing:  ./mathex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   Program       t o  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
                    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___.____________________________________________________________________________________________________________*
 *___________

                17.12.79           totalvariance

    Synopsis:    Return total varians of values

Declaration:     function  totalvariance(const  data:  Array  of  Extended)  :  float
                function  totalvariance(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

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 (731  ), stddev (726  ), mean (713  )


                Listing:  ./mathex/ex49.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   Program       t o  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       =   A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  TExArray       ;



                                                                                 730

                _____________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________
                    TV   :   f l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I : = 1  t o  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@ E x A r r a y[ 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___.____________________________________________________________________________________________________________*
 *___________

                17.12.80           variance

    Synopsis:    Return variance of values

Declaration:     function  variance(const  data:  Array  of  Extended)  :  float
                function  variance(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

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 (730  ), stddev (726  ), mean (713  )


                Listing:__./mathex/ex50.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 0;


                {   Program       t o  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   ;


                Var
                    I   :  1 . . 1 0 0 ;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;
                    V   :  f l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) do
                        E x A r r a y[i] : = (Random    - Random     ) * 1 0 0 ;
                    V := V a r i a n c e(E 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(@ E x A r r a y[ 1 ] , 1 0 0 ) ;
                    W r i t e l n(' V a r i a n c e( b )  :   ' ,V : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                17.13            einvalidargument



                17.13.1          Description

                Exception raised when invalid arguments are passed to a function.



                                                                                 731


Chapter   18


Reference   for   unit   'matrix'
18.1          Overview


The unit matrix is a unit that provides objects for the common two, three and four dimen-
sional vectors matrixes.  These vectors and matrixes are very common in computer graphics
and are often implemented from scratch by programmers while every implementation pro-
vides exactly the same functionality.

It makes therefore sense to provide this functionality in the runtime library.  This eliminates
the  need  for  programmers  to  reinvent  the  wheel  and  also  allows  libraries  that  use  matrix
operations to become more compatible.

The matrix unit does not provide n-dimensional matrixes.  The functionality needs of a gen-
eral  matrix  unit  varies  from  application  to  application;  one  can  think  of  reduced  memory
usage tricks for matrixes that only have data around the diagonal etc., desire for paralleliza-
tion etc.  etc.  It is believed that programmers that do use n-dimensional matrices would not
necessarily benfit from such a unit in the runtime library.

Design goals:


     o  Provide common dimensions, two three and four.

     o  Provide multiple floating point precisions, single, double, extended.

     o  Simple trivial binary representation; it is possible to typecast vectors into other imple-
        mentations that use the same trivial representation.

     o  No  dynamic  memory  management  in  the  background.   It  must  be  possible  to  write
        expressions like matrix A * B * C without worrying about memory management.


Design decisions:


     o  Class object model is ruled out.  The objects object model, without virtual methods,
        is suitable.

     o  Operator overloading is a good way to allow programmers to write matrix expressions.

     o  3 dimensions * 3 precision means 9 vector and 9 matrix objects.  Macro's have been
        used in the source to take care of this.



                                                             732

__________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________________________*
 *___
18.2          Constants,  types  and  variables



18.2.1         Types

Tmatrix2_double_data  =  Array[0..1,0..1]  of  double


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix2_extended_data  =  Array[0..1,0..1]  of  extended


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix2_single_data  =  Array[0..1,0..1]  of  single


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix3_double_data  =  Array[0..2,0..2]  of  double


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix3_extended_data  =  Array[0..2,0..2]  of  extended


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix3_single_data  =  Array[0..2,0..2]  of  single


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix4_double_data  =  Array[0..3,0..3]  of  double


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.



                                                                 733

__________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________________________*
 *___
Tmatrix4_extended_data  =  Array[0..3,0..3]  of  extended


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tmatrix4_single_data  =  Array[0..3,0..3]  of  single


This is the matrix internal data for a matrix.  It uses a simple array structure so data from
other libraries that define their own matrix type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tvector2_double_data  =  Array[0..1]  of  double


This is the vector internal data for a vector.  It uses a simple array structure so data from
other libraries that define their own vector type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tvector2_extended_data  =  Array[0..1]  of  extended


This is the vector internal data for a vector.  It uses a simple array structure so data from
other libraries that define their own vector type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tvector2_single_data  =  Array[0..1]  of  single


This is the vector internal data for a vector.  It uses a simple array structure so data from
other libraries that define their own vector type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tvector3_double_data  =  Array[0..2]  of  double


This is the vector internal data for a vector.  It uses a simple array structure so data from
other libraries that define their own vector type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tvector3_extended_data  =  Array[0..2]  of  extended


This is the vector internal data for a vector.  It uses a simple array structure so data from
other libraries that define their own vector type as a simple array structure can simply be
moved to and from this data, or typecasted into it.  As this is the only field in the object,
the object itself can be used just as fine for typecasting purposes etc.


Tvector3_single_data  =  Array[0..2]  of  single

                                                                 734

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                This is the vector internal data for a vector.  It uses a simple array structure so data from
                other libraries that define their own vector type as a simple array structure can simply be
                moved to and from this data, or typecasted into it.  As this is the only field in the object,
                the object itself can be used just as fine for typecasting purposes etc.


                Tvector4_double_data  =  Array[0..3]  of  double


                This is the vector internal data for a vector.  It uses a simple array structure so data from
                other libraries that define their own vector type as a simple array structure can simply be
                moved to and from this data, or typecasted into it.  As this is the only field in the object,
                the object itself can be used just as fine for typecasting purposes etc.


                Tvector4_extended_data  =  Array[0..3]  of  extended


                This is the vector internal data for a vector.  It uses a simple array structure so data from
                other libraries that define their own vector type as a simple array structure can simply be
                moved to and from this data, or typecasted into it.  As this is the only field in the object,
                the object itself can be used just as fine for typecasting purposes etc.


                Tvector4_single_data  =  Array[0..3]  of  single


                This is the vector internal data for a vector.  It uses a simple array structure so data from
                other libraries that define their own vector type as a simple array structure can simply be
                moved to and from this data, or typecasted into it.  As this is the only field in the object,
                the object itself can be used just as fine for typecasting purposes etc.
                18.3          Procedures  and  functions



                18.3.1         operator  *(Tmatrix2__double,  double):  Tmatrix2__double

    Synopsis:    Multiply a two-dimensional double precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix2_double,  double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.2         operator *(Tmatrix2__double, Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Give product of two two-dimensional double precision matrices

Declaration:     function  operator  *(Tmatrix2_double,  Tmatrix2_double):  Tmatrix2_double
                                                                                                                                   *
 * (const  m1:  Tmatrix2_double;
                                                                                                                                   *
 * const  m2:  Tmatrix2_double)
                                                                                                                                   *
 *  :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                                                                                 735

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.3         operator *(Tmatrix2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Give product of a two-dimendional double precision matrix and vector

Declaration:     function  operator  *(Tmatrix2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  m:  Tmatrix2_double;
                                                                                                                                   *
 * const  v:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  two-dimensional  double  precision  matrices  with  a
                two dimensional double precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.
                18.3.4         operator  *(Tmatrix2__extended,  extended):  Tmatrix2__extended

    Synopsis:    Multiply a two-dimensional extended precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.5         operator *(Tmatrix2__extended, Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Give product of two two-dimensional extended precision matrices

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tmatrix2_extended,  Tmatrix2_extended):  Tmatrix2_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix2_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix2_extended)
                                                                                                                                   *
 *            :  Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.6         operator *(Tmatrix2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Give product of a two-dimendional extended precision matrix and vector

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tmatrix2_extended,  Tvector2_extended):  Tvector2_extended
                                                                                                                                   *
 *           (const  m:  Tmatrix2_extended;
                                                                                                                                   *
 *           const  v:  Tvector2_extended)
                                                                                                                                   *
 *            :  Tvector2_extended

    Visibility:   default



                                                                                 736

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
Description:     This operator allows you to multipy a two-dimensional extended precision matrices with a
                two dimensional extended precision vector.  A new vector is returned which is the product
                of the matrix and the vector.  The product is calculated using the well known matrix-vector
                multiplication algorithm.
                18.3.7         operator  *(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Multiply a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.8         operator  *(Tmatrix2__single,  Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Give product of two two-dimensional single precision matrices

Declaration:     function  operator  *(Tmatrix2_single,  Tmatrix2_single):  Tmatrix2_single
                                                                                                                                   *
 * (const  m1:  Tmatrix2_single;
                                                                                                                                   *
 * const  m2:  Tmatrix2_single)
                                                                                                                                   *
 *  :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.9         operator  *(Tmatrix2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Give product of a two-dimendional single precision matrix and vector

Declaration:     function  operator  *(Tmatrix2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  m:  Tmatrix2_single;
                                                                                                                                   *
 * const  v:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  two-dimensional  single  precision  matrices  with  a
                two dimensional single precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.
                18.3.10          operator  *(Tmatrix3__double,  double):  Tmatrix3__double

    Synopsis:    Multiply a three-dimensional double precision matrix bye a scalar



                                                                                 737

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
Declaration:     function  operator  *(Tmatrix3_double,  double):  Tmatrix3_double
                                                                                                                    (const  m:  Tma*
 *trix3_double;
                                                                                                                    const  x:  doub*
 *le)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:  default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.11          operator *(Tmatrix3__double, Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Give product of two three-dimensional double precision matrices

Declaration:     function  operator  *(Tmatrix3_double,  Tmatrix3_double):  Tmatrix3_double
                                                                                                                                   *
 * (const  m1:  Tmatrix3_double;
                                                                                                                                   *
 * const  m2:  Tmatrix3_double)
                                                                                                                                   *
 *  :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.12          operator *(Tmatrix3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Give product of a three-dimendional double precision matrix and vector

Declaration:     function  operator  *(Tmatrix3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  m:  Tmatrix3_double;
                                                                                                                                   *
 * const  v:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to multipy a three-dimensional double precision matrices with a
                three dimensional double precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.
                18.3.13          operator  *(Tmatrix3__extended,  extended):  Tmatrix3__extended

    Synopsis:    Multiply a three-dimensional extended precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                                                                                 738

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.14          operator *(Tmatrix3__extended, Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Give product of two three-dimensional extended precision matrices

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tmatrix3_extended,  Tmatrix3_extended):  Tmatrix3_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix3_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix3_extended)
                                                                                                                                   *
 *            :  Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.15          operator *(Tmatrix3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Give product of a three-dimendional extended precision matrix and vector

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tmatrix3_extended,  Tvector3_extended):  Tvector3_extended
                                                                                                                                   *
 *           (const  m:  Tmatrix3_extended;
                                                                                                                                   *
 *           const  v:  Tvector3_extended)
                                                                                                                                   *
 *            :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to multipy a three-dimensional extended precision matrices with a
                three dimensional extended precision vector.  A new vector is returned which is the product
                of the matrix and the vector.  The product is calculated using the well known matrix-vector
                multiplication algorithm.
                18.3.16          operator  *(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Multiply a three-dimensional single precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.17          operator  *(Tmatrix3__single,  Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Give product of two three-dimensional single precision matrices

Declaration:     function  operator  *(Tmatrix3_single,  Tmatrix3_single):  Tmatrix3_single
                                                                                                                                   *
 * (const  m1:  Tmatrix3_single;
                                                                                                                                   *
 * const  m2:  Tmatrix3_single)
                                                                                                                                   *
 *  :  Tmatrix3_single

    Visibility:   default



                                                                                 739

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.18          operator  *(Tmatrix3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Give product of a three-dimendional single precision matrix and vector

Declaration:     function  operator  *(Tmatrix3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  m:  Tmatrix3_single;
                                                                                                                                   *
 * const  v:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  three-dimensional  single  precision  matrices  with  a
                three dimensional single precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.
                18.3.19          operator  *(Tmatrix4__double,  double):  Tmatrix4__double

    Synopsis:    Multiply a four-dimensional double precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix4_double,  double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.20          operator *(Tmatrix4__double, Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Give product of two four-dimensional double precision matrices

Declaration:     function  operator  *(Tmatrix4_double,  Tmatrix4_double):  Tmatrix4_double
                                                                                                                                   *
 * (const  m1:  Tmatrix4_double;
                                                                                                                                   *
 * const  m2:  Tmatrix4_double)
                                                                                                                                   *
 *  :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.21          operator *(Tmatrix4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Give product of a four-dimendional double precision matrix and vector
                                                                                 740

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
Declaration:     function  operator  *(Tmatrix4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 *(const  m:  Tmatrix4_double;
                                                                                                                                   *
 *const  v:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:  default

Description:     This  operator  allows  you  to  multipy  a  four-dimensional  double  precision  matrices  with  a
                four dimensional double precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.
                18.3.22          operator  *(Tmatrix4__extended,  extended):  Tmatrix4__extended

    Synopsis:    Multiply a four-dimensional extended precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.23          operator *(Tmatrix4__extended, Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Give product of two four-dimensional extended precision matrices

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tmatrix4_extended,  Tmatrix4_extended):  Tmatrix4_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix4_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix4_extended)
                                                                                                                                   *
 *            :  Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.24          operator *(Tmatrix4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Give product of a four-dimendional extended precision matrix and vector

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tmatrix4_extended,  Tvector4_extended):  Tvector4_extended
                                                                                                                                   *
 *           (const  m:  Tmatrix4_extended;
                                                                                                                                   *
 *           const  v:  Tvector4_extended)
                                                                                                                                   *
 *            :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to multipy a four-dimensional extended precision matrices with a
                four dimensional extended precision vector.  A new vector is returned which is the product
                of the matrix and the vector.  The product is calculated using the well known matrix-vector
                multiplication algorithm.



                                                                                 741

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.25          operator  *(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Multiply a four-dimensional single precision matrix bye a scalar

Declaration:     function  operator  *(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.
                18.3.26          operator  *(Tmatrix4__single,  Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Give product of two four-dimensional single precision matrices

Declaration:     function  operator  *(Tmatrix4_single,  Tmatrix4_single):  Tmatrix4_single
                                                                                                                                   *
 * (const  m1:  Tmatrix4_single;
                                                                                                                                   *
 * const  m2:  Tmatrix4_single)
                                                                                                                                   *
 *  :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.
                18.3.27          operator  *(Tmatrix4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Give product of a four-dimendional single precision matrix and vector

Declaration:     function  operator  *(Tmatrix4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  m:  Tmatrix4_single;
                                                                                                                                   *
 * const  v:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  four-dimensional  single  precision  matrices  with  a
                four dimensional single precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.
                18.3.28          operator  *(Tvector2__double,  double):  Tvector2__double

    Synopsis:    Multiply a two-dimensional double precision vector by a scalar

Declaration:     function  operator  *(Tvector2_double,  double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 742

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.29          operator *(Tvector2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Multiply two vectors element wise

Declaration:     function  operator  *(Tvector2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  x:  Tvector2_double;
                                                                                                                                   *
 * const  y:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.30          operator  *(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Multiply a two-dimensional extended precision vector by a scalar

Declaration:     function  operator  *(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.
                18.3.31          operator *(Tvector2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Multiply two vectors element wise

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tvector2_extended,  Tvector2_extended):  Tvector2_extended
                                                                                                                                   *
 *           (const  x:  Tvector2_extended;
                                                                                                                                   *
 *           const  y:  Tvector2_extended)
                                                                                                                                   *
 *            :  Tvector2_extended

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.32          operator  *(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Multiply a two-dimensional single precision vector by a scalar

Declaration:     function  operator  *(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.

                                                                                 743

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.33          operator  *(Tvector2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Multiply two vectors element wise

Declaration:     function  operator  *(Tvector2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  x:  Tvector2_single;
                                                                                                                                   *
 * const  y:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.34          operator  *(Tvector3__double,  double):  Tvector3__double

    Synopsis:    Multiply a three-dimensional double precision vector by a scalar

Declaration:     function  operator  *(Tvector3_double,  double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.
                18.3.35          operator *(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Multiply two vectors element wise

Declaration:     function  operator  *(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  x:  Tvector3_double;
                                                                                                                                   *
 * const  y:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.36          operator  *(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Multiply a three-dimensional extended precision vector by a scalar

Declaration:     function  operator  *(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 744

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.37          operator *(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Multiply two vectors element wise

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tvector3_extended,  Tvector3_extended):  Tvector3_extended
                                                                                                                                   *
 *           (const  x:  Tvector3_extended;
                                                                                                                                   *
 *           const  y:  Tvector3_extended)
                                                                                                                                   *
 *            :  Tvector3_extended

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.38          operator  *(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Multiply a three-dimensional single precision vector by a scalar

Declaration:     function  operator  *(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.
                18.3.39          operator  *(Tvector3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Multiply two vectors element wise

Declaration:     function  operator  *(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  x:  Tvector3_single;
                                                                                                                                   *
 * const  y:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.40          operator  *(Tvector4__double,  double):  Tvector4__double

    Synopsis:    Multiply a four-dimensional double precision vector by a scalar

Declaration:     function  operator  *(Tvector4_double,  double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.

                                                                                 745

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.41          operator *(Tvector4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Multiply two vectors element wise

Declaration:     function  operator  *(Tvector4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 * (const  x:  Tvector4_double;
                                                                                                                                   *
 * const  y:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.42          operator  *(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Multiply a four-dimensional extended precision vector by a scalar

Declaration:     function  operator  *(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.
                18.3.43          operator *(Tvector4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Multiply two vectors element wise

Declaration:
                                                                                                                                   *
 *           function  operator  *(Tvector4_extended,  Tvector4_extended):  Tvector4_extended
                                                                                                                                   *
 *           (const  x:  Tvector4_extended;
                                                                                                                                   *
 *           const  y:  Tvector4_extended)
                                                                                                                                   *
 *            :  Tvector4_extended

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.44          operator  *(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Multiply a four-dimensional single precision vector by a scalar

Declaration:     function  operator  *(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.

                                                                                 746

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.45          operator  *(Tvector4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Multiply two vectors element wise

Declaration:     function  operator  *(Tvector4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  x:  Tvector4_single;
                                                                                                                                   *
 * const  y:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.
                18.3.46          operator  **(Tvector2__double,  Tvector2__double):  double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector2_double,  Tvector2_double):  double
                                                                                                                      (const  x:  T*
 *vector2_double;
                                                                                                                      const  y:  Tv*
 *ector2_double)
                                                                                                                        :  double

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.47          operator  **(Tvector2__extended,  Tvector2__extended):  extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector2_extended,  Tvector2_extended):  extended
                                                                                                                                (co*
 *nst  x:  Tvector2_extended;
                                                                                                                                con*
 *st  y:  Tvector2_extended)
                                                                                                                                  :*
 *  extended

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.48          operator  **(Tvector2__single,  Tvector2__single):  single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector2_single,  Tvector2_single):  single
                                                                                                                      (const  x:  T*
 *vector2_single;
                                                                                                                      const  y:  Tv*
 *ector2_single)
                                                                                                                        :  single

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                                                                                 747

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.49          operator  **(Tvector3__double,  Tvector3__double):  double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector3_double,  Tvector3_double):  double
                                                                                                                      (const  x:  T*
 *vector3_double;
                                                                                                                      const  y:  Tv*
 *ector3_double)
                                                                                                                        :  double

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.50          operator  **(Tvector3__extended,  Tvector3__extended):  extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector3_extended,  Tvector3_extended):  extended
                                                                                                                                (co*
 *nst  x:  Tvector3_extended;
                                                                                                                                con*
 *st  y:  Tvector3_extended)
                                                                                                                                  :*
 *  extended

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.51          operator  **(Tvector3__single,  Tvector3__single):  single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector3_single,  Tvector3_single):  single
                                                                                                                      (const  x:  T*
 *vector3_single;
                                                                                                                      const  y:  Tv*
 *ector3_single)
                                                                                                                        :  single

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.52          operator  **(Tvector4__double,  Tvector4__double):  double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector4_double,  Tvector4_double):  double
                                                                                                                      (const  x:  T*
 *vector4_double;
                                                                                                                      const  y:  Tv*
 *ector4_double)
                                                                                                                        :  double

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                                                                                 748

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.53          operator  **(Tvector4__extended,  Tvector4__extended):  extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector4_extended,  Tvector4_extended):  extended
                                                                                                                                (co*
 *nst  x:  Tvector4_extended;
                                                                                                                                con*
 *st  y:  Tvector4_extended)
                                                                                                                                  :*
 *  extended

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.54          operator  **(Tvector4__single,  Tvector4__single):  single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     function  operator  **(Tvector4_single,  Tvector4_single):  single
                                                                                                                      (const  x:  T*
 *vector4_single;
                                                                                                                      const  y:  Tv*
 *ector4_single)
                                                                                                                        :  single

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.
                18.3.55          operator  +(Tmatrix2__double,  double):  Tmatrix2__double

    Synopsis:    Add scalar to two-dimensional double precision matrix

Declaration:     function  operator  +(Tmatrix2_double,  double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.56          operator +(Tmatrix2__double, Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Add two two-dimensional double precision matrices together.

Declaration:     function  operator  +(Tmatrix2_double,  Tmatrix2_double):  Tmatrix2_double
                                                                                                                                   *
 * (const  m1:  Tmatrix2_double;
                                                                                                                                   *
 * const  m2:  Tmatrix2_double)
                                                                                                                                   *
 *  :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to add two two-dimensional double precision matrices together.  A
                new matrix is returned with all elements of the two matrices added together.



                                                                                 749

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.57          operator  +(Tmatrix2__extended,  extended):  Tmatrix2__extended

    Synopsis:    Add scalar to two-dimensional extended precision matrix

Declaration:     function  operator  +(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.58          operator +(Tmatrix2__extended, Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Add two two-dimensional extended precision matrices together.

Declaration:
                                                                                                                                   *
 *           function  operator  +(Tmatrix2_extended,  Tmatrix2_extended):  Tmatrix2_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix2_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix2_extended)
                                                                                                                                   *
 *            :  Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to add two two-dimensional extended precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.
                18.3.59          operator  +(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Add scalar to two-dimensional single precision matrix

Declaration:     function  operator  +(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.60          operator  +(Tmatrix2__single,  Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Add two two-dimensional single precision matrices together.

Declaration:     function  operator  +(Tmatrix2_single,  Tmatrix2_single):  Tmatrix2_single
                                                                                                                                   *
 * (const  m1:  Tmatrix2_single;
                                                                                                                                   *
 * const  m2:  Tmatrix2_single)
                                                                                                                                   *
 *  :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to add two two-dimensional single precision matrices together.  A
                new matrix is returned with all elements of the two matrices added together.

                                                                                 750

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.61          operator  +(Tmatrix3__double,  double):  Tmatrix3__double

    Synopsis:    Add scalar to three-dimensional double precision matrix

Declaration:     function  operator  +(Tmatrix3_double,  double):  Tmatrix3_double
                                                                                                                     (const  m:  Tm*
 *atrix3_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.62          operator +(Tmatrix3__double, Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Add two three-dimensional double precision matrices together.

Declaration:     function  operator  +(Tmatrix3_double,  Tmatrix3_double):  Tmatrix3_double
                                                                                                                                   *
 * (const  m1:  Tmatrix3_double;
                                                                                                                                   *
 * const  m2:  Tmatrix3_double)
                                                                                                                                   *
 *  :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to add two three-dimensional double precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.
                18.3.63          operator  +(Tmatrix3__extended,  extended):  Tmatrix3__extended

    Synopsis:    Add scalar to three-dimensional extended precision matrix

Declaration:     function  operator  +(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.64          operator +(Tmatrix3__extended, Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Add two three-dimensional extended precision matrices together.

Declaration:
                                                                                                                                   *
 *           function  operator  +(Tmatrix3_extended,  Tmatrix3_extended):  Tmatrix3_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix3_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix3_extended)
                                                                                                                                   *
 *            :  Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to add two three-dimensional extended precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.

                                                                                 751

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.65          operator  +(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Add scalar to three-dimensional single precision matrix

Declaration:     function  operator  +(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.66          operator  +(Tmatrix3__single,  Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Add two three-dimensional single precision matrices together.

Declaration:     function  operator  +(Tmatrix3_single,  Tmatrix3_single):  Tmatrix3_single
                                                                                                                                   *
 * (const  m1:  Tmatrix3_single;
                                                                                                                                   *
 * const  m2:  Tmatrix3_single)
                                                                                                                                   *
 *  :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to add two three-dimensional single precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.
                18.3.67          operator  +(Tmatrix4__double,  double):  Tmatrix4__double

    Synopsis:    Add scalar to four-dimensional double precision matrix

Declaration:     function  operator  +(Tmatrix4_double,  double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.68          operator +(Tmatrix4__double, Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Add two four-dimensional double precision matrices together.

Declaration:     function  operator  +(Tmatrix4_double,  Tmatrix4_double):  Tmatrix4_double
                                                                                                                                   *
 * (const  m1:  Tmatrix4_double;
                                                                                                                                   *
 * const  m2:  Tmatrix4_double)
                                                                                                                                   *
 *  :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to add two four-dimensional double precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.



                                                                                 752

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.69          operator  +(Tmatrix4__extended,  extended):  Tmatrix4__extended

    Synopsis:    Add scalar to four-dimensional extended precision matrix

Declaration:     function  operator  +(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.70          operator +(Tmatrix4__extended, Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Add two four-dimensional extended precision matrices together.

Declaration:
                                                                                                                                   *
 *           function  operator  +(Tmatrix4_extended,  Tmatrix4_extended):  Tmatrix4_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix4_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix4_extended)
                                                                                                                                   *
 *            :  Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to add two four-dimensional extended precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.
                18.3.71          operator  +(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Add scalar to four-dimensional single precision matrix

Declaration:     function  operator  +(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.
                18.3.72          operator  +(Tmatrix4__single,  Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Add two four-dimensional single precision matrices together.

Declaration:     function  operator  +(Tmatrix4_single,  Tmatrix4_single):  Tmatrix4_single
                                                                                                                                   *
 * (const  m1:  Tmatrix4_single;
                                                                                                                                   *
 * const  m2:  Tmatrix4_single)
                                                                                                                                   *
 *  :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to add two four-dimensional single precision matrices together.  A
                new matrix is returned with all elements of the two matrices added together.

                                                                                 753

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.73          operator  +(Tvector2__double,  double):  Tvector2__double

    Synopsis:    Add scalar to two-dimensional double precision vector

Declaration:     function  operator  +(Tvector2_double,  double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.74          operator +(Tvector2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Add two-dimensional double precision vectors together

Declaration:     function  operator  +(Tvector2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  x:  Tvector2_double;
                                                                                                                                   *
 * const  y:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to add two two-dimensional vectors with double precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.
                18.3.75          operator  +(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Add scalar to two-dimensional extended precision vector

Declaration:     function  operator  +(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.76          operator +(Tvector2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Add two-dimensional extended precision vectors together

Declaration:
                                                                                                                                   *
 *           function  operator  +(Tvector2_extended,  Tvector2_extended):  Tvector2_extended
                                                                                                                                   *
 *           (const  x:  Tvector2_extended;
                                                                                                                                   *
 *           const  y:  Tvector2_extended)
                                                                                                                                   *
 *            :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to add two two-dimensional vectors with extended precision to-
                gether.  The result is a new vector which consists of the sums of the individual elements of
                the two vectors.



                                                                                 754

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.77          operator  +(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Add scalar to two-dimensional single precision vector

Declaration:     function  operator  +(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.78          operator  +(Tvector2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Add two-dimensional single precision vectors together

Declaration:     function  operator  +(Tvector2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  x:  Tvector2_single;
                                                                                                                                   *
 * const  y:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to add two two-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.
                18.3.79          operator  +(Tvector3__double,  double):  Tvector3__double

    Synopsis:    Add scalar to three-dimensional double precision vector

Declaration:     function  operator  +(Tvector3_double,  double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.80          operator +(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Add three-dimensional double precision vectors together

Declaration:     function  operator  +(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  x:  Tvector3_double;
                                                                                                                                   *
 * const  y:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  add  two  three-dimensional  vectors  with  double  precision  to-
                gether.  The result is a new vector which consists of the sums of the individual elements of
                the two vectors.



                                                                                 755

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.81          operator  +(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Add scalar to three-dimensional extended precision vector

Declaration:     function  operator  +(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.82          operator +(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Add three-dimensional extended precision vectors together

Declaration:
                                                                                                                                   *
 *           function  operator  +(Tvector3_extended,  Tvector3_extended):  Tvector3_extended
                                                                                                                                   *
 *           (const  x:  Tvector3_extended;
                                                                                                                                   *
 *           const  y:  Tvector3_extended)
                                                                                                                                   *
 *            :  Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  two  three-dimensional  vectors  with  extended  precision
                together.  The result is a new vector which consists of the sums of the individual elements of
                the two vectors.
                18.3.83          operator  +(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Add scalar to three-dimensional single precision vector

Declaration:     function  operator  +(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.84          operator  +(Tvector3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Add three-dimensional extended precision vectors together

Declaration:     function  operator  +(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  x:  Tvector3_single;
                                                                                                                                   *
 * const  y:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to add two three-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.



                                                                                 756

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.85          operator  +(Tvector4__double,  double):  Tvector4__double

    Synopsis:    Add scalar to four-dimensional double precision vector

Declaration:     function  operator  +(Tvector4_double,  double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.86          operator +(Tvector4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Add four-dimensional double precision vectors together

Declaration:     function  operator  +(Tvector4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 * (const  x:  Tvector4_double;
                                                                                                                                   *
 * const  y:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to add two four-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.
                18.3.87          operator  +(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Add scalar to four-dimensional extended precision vector

Declaration:     function  operator  +(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.88          operator +(Tvector4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Add four-dimensional extended precision vectors together

Declaration:
                                                                                                                                   *
 *           function  operator  +(Tvector4_extended,  Tvector4_extended):  Tvector4_extended
                                                                                                                                   *
 *           (const  x:  Tvector4_extended;
                                                                                                                                   *
 *           const  y:  Tvector4_extended)
                                                                                                                                   *
 *            :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to add two two-dimensional vectors with extended precision to-
                gether.  The result is a new vector which consists of the sums of the individual elements of
                the two vectors.



                                                                                 757

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.89          operator  +(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Add scalar to four-dimensional single precision vector

Declaration:     function  operator  +(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.
                18.3.90          operator  +(Tvector4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Add four-dimensional single precision vectors together

Declaration:     function  operator  +(Tvector4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  x:  Tvector4_single;
                                                                                                                                   *
 * const  y:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to add two four-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.
                18.3.91          operator  -(Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Negate two-dimensional double precision matrix.

Declaration:     function  operator  -(Tmatrix2_double):  Tmatrix2_double
                                                                                                        (const  m1:  Tmatrix2_doubl*
 *e)
                                                                                                         :  Tmatrix2_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.92          operator  -(Tmatrix2__double,  double):  Tmatrix2__double

    Synopsis:    Subtract scalar to two-dimensional double precision matrix

Declaration:     function  operator  -(Tmatrix2_double,  double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                                                                                 758

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.93          operator -(Tmatrix2__double, Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Subtract a two-dimensional double precision matrix from another.

Declaration:     function  operator  -(Tmatrix2_double,  Tmatrix2_double):  Tmatrix2_double
                                                                                                                                   *
 * (const  m1:  Tmatrix2_double;
                                                                                                                                   *
 * const  m2:  Tmatrix2_double)
                                                                                                                                   *
 *  :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to subtract a two-dimensional double precision matrix from an-
                other.  A new matrix is returned with all elements of the two matrices subtracted from each
                other.
                18.3.94          operator  -(Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Negate two-dimensional extended precision matrix.

Declaration:     function  operator  -(Tmatrix2_extended):  Tmatrix2_extended
                                                                                                              (const  m1:  Tmatrix2*
 *_extended)
                                                                                                                :  Tmatrix2_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.95          operator  -(Tmatrix2__extended,  extended):  Tmatrix2__extended

    Synopsis:    Add scalar to two-dimensional extended precision matrix

Declaration:     function  operator  -(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                18.3.96          operator -(Tmatrix2__extended, Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Subtract a two-dimensional extended precision matrix from another.

Declaration:
                                                                                                                                   *
 *           function  operator  -(Tmatrix2_extended,  Tmatrix2_extended):  Tmatrix2_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix2_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix2_extended)
                                                                                                                                   *
 *            :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  a  two-dimensional  extended  precision  matrix  from
                another.  A new matrix is returned with all elements of the two matrices subtracted from
                each other.

                                                                                 759

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.97          operator  -(Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Negate two-dimensional single precision matrix.

Declaration:     function  operator  -(Tmatrix2_single):  Tmatrix2_single
                                                                                                        (const  m1:  Tmatrix2_singl*
 *e)
                                                                                                         :  Tmatrix2_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.98          operator  -(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Subtract scalar to two-dimensional single precision matrix

Declaration:     function  operator  -(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                18.3.99          operator  -(Tmatrix2__single,  Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Subtract a two-dimensional single precision matrix from another.

Declaration:     function  operator  -(Tmatrix2_single,  Tmatrix2_single):  Tmatrix2_single
                                                                                                                                   *
 * (const  m1:  Tmatrix2_single;
                                                                                                                                   *
 * const  m2:  Tmatrix2_single)
                                                                                                                                   *
 *  :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to subtract a two-dimensional single precision matrix from another.
                A new matrix is returned with all elements of the two matrices subtracted from each other.
                18.3.100           operator  -(Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Negate three-dimensional double precision matrix.

Declaration:     function  operator  -(Tmatrix3_double):  Tmatrix3_double
                                                                                                        (const  m1:  Tmatrix3_doubl*
 *e)
                                                                                                         :  Tmatrix3_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.


                                                                                 760

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.101           operator  -(Tmatrix3__double,  double):  Tmatrix3__double

    Synopsis:    Add scalar to three-dimensional double precision matrix

Declaration:     function  operator  -(Tmatrix3_double,  double):  Tmatrix3_double
                                                                                                                     (const  m:  Tm*
 *atrix3_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                18.3.102           operator -(Tmatrix3__double, Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Subtract a three-dimensional double precision matrix from another.

Declaration:     function  operator  -(Tmatrix3_double,  Tmatrix3_double):  Tmatrix3_double
                                                                                                                                   *
 * (const  m1:  Tmatrix3_double;
                                                                                                                                   *
 * const  m2:  Tmatrix3_double)
                                                                                                                                   *
 *  :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  a  three-dimensional  double  precision  matrix  from
                another.  A new matrix is returned with all elements of the two matrices subtracted from
                each other.
                18.3.103           operator  -(Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Negate three-dimensional extended precision matrix.

Declaration:     function  operator  -(Tmatrix3_extended):  Tmatrix3_extended
                                                                                                              (const  m1:  Tmatrix3*
 *_extended)
                                                                                                                :  Tmatrix3_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.104           operator -(Tmatrix3__extended, extended):  Tmatrix3__extended

    Synopsis:    Add scalar to three-dimensional extended precision matrix

Declaration:     function  operator  -(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to substract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                                                                                 761

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.105           operator -(Tmatrix3__extended, Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Subtract a three-dimensional extended precision matrix from another.

Declaration:
                                                                                                                                   *
 *           function  operator  -(Tmatrix3_extended,  Tmatrix3_extended):  Tmatrix3_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix3_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix3_extended)
                                                                                                                                   *
 *            :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  a  three-dimensional  extended  precision  matrix  from
                another.  A new matrix is returned with all elements of the two matrices subtracted from
                each other.
                18.3.106           operator  -(Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Negate three-dimensional single precision matrix.

Declaration:     function  operator  -(Tmatrix3_single):  Tmatrix3_single
                                                                                                        (const  m1:  Tmatrix3_singl*
 *e)
                                                                                                         :  Tmatrix3_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.107           operator  -(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Add scalar to three-dimensional single precision matrix

Declaration:     function  operator  -(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                18.3.108           operator  -(Tmatrix3__single,  Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Subtract a three-dimensional single precision matrix from another.

Declaration:     function  operator  -(Tmatrix3_single,  Tmatrix3_single):  Tmatrix3_single
                                                                                                                                   *
 * (const  m1:  Tmatrix3_single;
                                                                                                                                   *
 * const  m2:  Tmatrix3_single)
                                                                                                                                   *
 *  :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to subtract a three-dimensional single precision matrix from an-
                other.  A new matrix is returned with all elements of the two matrices subtracted from each
                other.

                                                                                 762

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.109           operator  -(Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Negate four-dimensional double precision matrix.

Declaration:     function  operator  -(Tmatrix4_double):  Tmatrix4_double
                                                                                                        (const  m1:  Tmatrix4_doubl*
 *e)
                                                                                                         :  Tmatrix4_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.110           operator  -(Tmatrix4__double,  double):  Tmatrix4__double

    Synopsis:    Add scalar to four-dimensional double precision matrix

Declaration:     function  operator  -(Tmatrix4_double,  double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                18.3.111           operator -(Tmatrix4__double, Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Subtract a four-dimensional double precision matrix from another.

Declaration:     function  operator  -(Tmatrix4_double,  Tmatrix4_double):  Tmatrix4_double
                                                                                                                                   *
 * (const  m1:  Tmatrix4_double;
                                                                                                                                   *
 * const  m2:  Tmatrix4_double)
                                                                                                                                   *
 *  :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to subtract a four-dimensional double precision matrix from an-
                other.  A new matrix is returned with all elements of the two matrices subtracted from each
                other.
                18.3.112           operator  -(Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Negate four-dimensional extended precision matrix.

Declaration:     function  operator  -(Tmatrix4_extended):  Tmatrix4_extended
                                                                                                              (const  m1:  Tmatrix4*
 *_extended)
                                                                                                                :  Tmatrix4_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                                                                                 763

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.113           operator -(Tmatrix4__extended, extended):  Tmatrix4__extended

    Synopsis:    Add scalar to four-dimensional extended precision matrix

Declaration:     function  operator  -(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.
                18.3.114           operator -(Tmatrix4__extended, Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Subtract a four-dimensional extended precision matrix from another.

Declaration:
                                                                                                                                   *
 *           function  operator  -(Tmatrix4_extended,  Tmatrix4_extended):  Tmatrix4_extended
                                                                                                                                   *
 *           (const  m1:  Tmatrix4_extended;
                                                                                                                                   *
 *           const  m2:  Tmatrix4_extended)
                                                                                                                                   *
 *            :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  a  four-dimensional  extended  precision  matrix  from
                another.  A new matrix is returned with all elements of the two matrices subtracted from
                each other.
                18.3.115           operator  -(Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Negate four-dimensional single precision matrix.

Declaration:     function  operator  -(Tmatrix4_single):  Tmatrix4_single
                                                                                                        (const  m1:  Tmatrix4_singl*
 *e)
                                                                                                         :  Tmatrix4_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.
                18.3.116           operator  -(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Add scalar to four-dimensional single precision matrix

Declaration:     function  operator  -(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                                                                                 764

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.117           operator  -(Tmatrix4__single,  Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Subtract a four-dimensional single precision matrix from another.

Declaration:     function  operator  -(Tmatrix4_single,  Tmatrix4_single):  Tmatrix4_single
                                                                                                                                   *
 * (const  m1:  Tmatrix4_single;
                                                                                                                                   *
 * const  m2:  Tmatrix4_single)
                                                                                                                                   *
 *  :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to subtract a four-dimensional single precision matrix from another.
                A new matrix is returned with all elements of the two matrices subtracted from each other.
                18.3.118           operator  -(Tvector2__double):  Tvector2__double

    Synopsis:    Negate two-dimensional vector.

Declaration:     function  operator  -(Tvector2_double):  Tvector2_double
                                                                                                        (const  x:  Tvector2_double)
                                                                                                         :  Tvector2_double

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.119           operator  -(Tvector2__double,  double):  Tvector2__double

    Synopsis:    Subtract scalar from two-dimensional double precision vector

Declaration:     function  operator  -(Tvector2_double,  double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.120           operator -(Tvector2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Subtract two-dimensional double precision vectors from each other

Declaration:     function  operator  -(Tvector2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  x:  Tvector2_double;
                                                                                                                                   *
 * const  y:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  two-dimensional  vectors  with  double  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                                                                                 765

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.121           operator  -(Tvector2__extended):  Tvector2__extended

    Synopsis:    Negate two-dimensional vector.

Declaration:     function  operator  -(Tvector2_extended):  Tvector2_extended
                                                                                                              (const  x:  Tvector2_*
 *extended)
                                                                                                                :  Tvector2_extended

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.122           operator  -(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Subtract scalar from two-dimensional extended precision vector

Declaration:     function  operator  -(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.123           operator -(Tvector2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Subtract two-dimensional extended precision vectors from each other

Declaration:
                                                                                                                                   *
 *           function  operator  -(Tvector2_extended,  Tvector2_extended):  Tvector2_extended
                                                                                                                                   *
 *           (const  x:  Tvector2_extended;
                                                                                                                                   *
 *           const  y:  Tvector2_extended)
                                                                                                                                   *
 *            :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to subtract two two-dimensional vectors with extended precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.
                18.3.124           operator  -(Tvector2__single):  Tvector2__single

    Synopsis:    Negate two-dimensional vector.

Declaration:     function  operator  -(Tvector2_single):  Tvector2_single
                                                                                                        (const  x:  Tvector2_single)
                                                                                                         :  Tvector2_single

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                                                                                 766

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.125           operator  -(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Subtract scalar from two-dimensional single precision vector

Declaration:     function  operator  -(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.126           operator  -(Tvector2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Subtract two-dimensional single precision vectors from each other

Declaration:     function  operator  -(Tvector2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  x:  Tvector2_single;
                                                                                                                                   *
 * const  y:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to subtract two two-dimensional vectors with single precision from
                each  other.   The  result  is  a  new  vector  which  consists  of  the  difference  of  the  individual
                elements of the two vectors.
                18.3.127           operator  -(Tvector3__double):  Tvector3__double

    Synopsis:    Negate three-dimensional vector.

Declaration:     function  operator  -(Tvector3_double):  Tvector3_double
                                                                                                        (const  x:  Tvector3_double)
                                                                                                         :  Tvector3_double

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.128           operator  -(Tvector3__double,  double):  Tvector3__double

    Synopsis:    Subtract scalar from three-dimensional double precision vector

Declaration:     function  operator  -(Tvector3_double,  double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                                                                                 767

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.129           operator -(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Subtract three-dimensional double precision vectors from each other

Declaration:     function  operator  -(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  x:  Tvector3_double;
                                                                                                                                   *
 * const  y:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  two-dimensional  vectors  with  double  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.
                18.3.130           operator  -(Tvector3__extended):  Tvector3__extended

    Synopsis:    Negate three-dimensional vector.

Declaration:     function  operator  -(Tvector3_extended):  Tvector3_extended
                                                                                                              (const  x:  Tvector3_*
 *extended)
                                                                                                                :  Tvector3_extended

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.131           operator  -(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Subtract scalar from three-dimensional extended precision vector

Declaration:     function  operator  -(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.132           operator -(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Subtract three-dimensional extended precision vectors from each other

Declaration:
                                                                                                                                   *
 *           function  operator  -(Tvector3_extended,  Tvector3_extended):  Tvector3_extended
                                                                                                                                   *
 *           (const  x:  Tvector3_extended;
                                                                                                                                   *
 *           const  y:  Tvector3_extended)
                                                                                                                                   *
 *            :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to subtract two three-dimensional vectors with extended precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                                                                                 768

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.133           operator  -(Tvector3__single):  Tvector3__single

    Synopsis:    Negate three-dimensional vector.

Declaration:     function  operator  -(Tvector3_single):  Tvector3_single
                                                                                                        (const  x:  Tvector3_single)
                                                                                                         :  Tvector3_single

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.134           operator  -(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Subtract scalar from three-dimensional single precision vector

Declaration:     function  operator  -(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.135           operator  -(Tvector3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Subtract three-dimensional single precision vectors from each other

Declaration:     function  operator  -(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  x:  Tvector3_single;
                                                                                                                                   *
 * const  y:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  three-dimensional  vectors  with  single  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.
                18.3.136           operator  -(Tvector4__double):  Tvector4__double

    Synopsis:    Negate four-dimensional vector.

Declaration:     function  operator  -(Tvector4_double):  Tvector4_double
                                                                                                        (const  x:  Tvector4_double)
                                                                                                         :  Tvector4_double

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                                                                                 769

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.137           operator  -(Tvector4__double,  double):  Tvector4__double

    Synopsis:    Subtract scalar from four-dimensional double precision vector

Declaration:     function  operator  -(Tvector4_double,  double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.138           operator -(Tvector4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Subtract four-dimensional double precision vectors from each other

Declaration:     function  operator  -(Tvector4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 * (const  x:  Tvector4_double;
                                                                                                                                   *
 * const  y:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  four-dimensional  vectors  with  double  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.
                18.3.139           operator  -(Tvector4__extended):  Tvector4__extended

    Synopsis:    Negate four-dimensional vector.

Declaration:     function  operator  -(Tvector4_extended):  Tvector4_extended
                                                                                                              (const  x:  Tvector4_*
 *extended)
                                                                                                                :  Tvector4_extended

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.140           operator  -(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Subtract scalar from four-dimensional extended precision vector

Declaration:     function  operator  -(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                                                                                 770

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.141           operator -(Tvector4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Subtract four-dimensional extended precision vectors from each other

Declaration:
                                                                                                                                   *
 *           function  operator  -(Tvector4_extended,  Tvector4_extended):  Tvector4_extended
                                                                                                                                   *
 *           (const  x:  Tvector4_extended;
                                                                                                                                   *
 *           const  y:  Tvector4_extended)
                                                                                                                                   *
 *            :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to subtract two four-dimensional vectors with extended precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.
                18.3.142           operator  -(Tvector4__single):  Tvector4__single

    Synopsis:    Negate four-dimensional vector.

Declaration:     function  operator  -(Tvector4_single):  Tvector4_single
                                                                                                        (const  x:  Tvector4_single)
                                                                                                         :  Tvector4_single

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.
                18.3.143           operator  -(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Subtract scalar from four-dimensional single precision vector

Declaration:     function  operator  -(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.
                18.3.144           operator  -(Tvector4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Subtract four-dimensional single precision vectors from each other

Declaration:     function  operator  -(Tvector4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  x:  Tvector4_single;
                                                                                                                                   *
 * const  y:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  four-dimensional  vectors  with  single  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                                                                                 771

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.145           operator  /(Tmatrix2__double,  double):  Tmatrix2__double

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix2_double,  double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.146           operator /(Tmatrix2__extended, extended):  Tmatrix2__extended

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.147           operator  /(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.148           operator  /(Tmatrix3__double,  double):  Tmatrix3__double

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix3_double,  double):  Tmatrix3_double
                                                                                                                     (const  m:  Tm*
 *atrix3_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                                                                                 772

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.149           operator /(Tmatrix3__extended, extended):  Tmatrix3__extended

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.150           operator  /(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.151           operator  /(Tmatrix4__double,  double):  Tmatrix4__double

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix4_double,  double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.152           operator /(Tmatrix4__extended, extended):  Tmatrix4__extended

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                                                                                 773

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.153           operator  /(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Divide a two-dimensional single precision matrix bye a scalar

Declaration:     function  operator  /(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.
                18.3.154           operator  /(Tvector2__double,  double):  Tvector2__double

    Synopsis:    Divide a two-dimensional double precision vector by a scalar

Declaration:     function  operator  /(Tvector2_double,  double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.155           operator  /(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Divide a two-dimensional extended precision vector by a scalar

Declaration:     function  operator  /(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.156           operator  /(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Divide a two-dimensional single precision vector by a scalar

Declaration:     function  operator  /(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                                                                                 774

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.157           operator  /(Tvector3__double,  double):  Tvector3__double

    Synopsis:    Divide a three-dimensional double precision vector by a scalar

Declaration:     function  operator  /(Tvector3_double,  double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.158           operator  /(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Divide a three-dimensional extended precision vector by a scalar

Declaration:     function  operator  /(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.159           operator  /(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Divide a three-dimensional single precision vector by a scalar

Declaration:     function  operator  /(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.160           operator  /(Tvector4__double,  double):  Tvector4__double

    Synopsis:    Divide a four-dimensional double precision vector by a scalar

Declaration:     function  operator  /(Tvector4_double,  double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                                                                                 775

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.161           operator  /(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Divide a four-dimensional extended precision vector by a scalar

Declaration:     function  operator  /(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.162           operator  /(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Divide a four-dimensional single precision vector by a scalar

Declaration:     function  operator  /(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.
                18.3.163           operator  :=(Tmatrix2__double):  Tmatrix2__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix2_d*
 *ouble)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with extended precision is expected.
                18.3.164           operator  :=(Tmatrix2__double):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with single precision is expected.  Some accurace is lost
                because of the conversion.

                                                                                 776

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.165           operator  :=(Tmatrix2__double):  Tmatrix3__double

    Synopsis:    Allow assignment of two-dimensional double precision matrix to three-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with double precision is expected.  The extra fields are
                set to 0.
                18.3.166           operator  :=(Tmatrix2__double):  Tmatrix3__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to three-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix2_d*
 *ouble)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with extended precision is expected.  The extra fields
                are set to 0.
                18.3.167           operator  :=(Tmatrix2__double):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with single precision is expected.  The extra fields are set to
                0 and some accuracy is lost because of the conversion.
                18.3.168           operator  :=(Tmatrix2__double):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with double precision is expected.  The extra fields are
                set to 0.



                                                                                 777

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.169           operator  :=(Tmatrix2__double):  Tmatrix4__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix2_d*
 *ouble)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever  a  four-dimensional  matrix  with  extended  precision  is  expected.  The  extra  fields
                are set to 0.
                18.3.170           operator  :=(Tmatrix2__double):  Tmatrix4__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_double):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with single precision is expected.  The extra fields are
                set to 0 and some precision is lost because of the conversion.
                18.3.171           operator  :=(Tmatrix2__extended):  Tmatrix2__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix2_double
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional two with extended precision values wher-
                ever  a  two-dimensional  matrix  with  double  precision  is  expected.   Some  accuracy  is  lost
                because of the conversion.
                18.3.172           operator  :=(Tmatrix2__extended):  Tmatrix2__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix2_single
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with single precision is expected.  Some accuracy is lost
                because of the conversion.



                                                                                 778

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.173           operator  :=(Tmatrix2__extended):  Tmatrix3__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to three-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix3_double
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with double precision is expected.  The extra fields are
                set to 0 and some accuracy is lost because of the conversion.
                18.3.174           operator  :=(Tmatrix2__extended):  Tmatrix3__extended

    Synopsis:    Allow  assignment  of  two-dimensional  extended  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix3_extended
                                                                                                                (const  v:  Tmatrix*
 *2_extended)
                                                                                                                  :  Tmatrix3_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with extended precision is expected.  The extra fields
                are set to 0.
                18.3.175           operator  :=(Tmatrix2__extended):  Tmatrix3__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix3_single
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with single precision is expected.  The extra fields are
                set to 0 and some accuracy is lost because of the conversion.
                18.3.176           operator  :=(Tmatrix2__extended):  Tmatrix4__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix4_double
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with double precision is expected.  The extra fields are
                set to 0 and some accuracy is lost because of the conversion.



                                                                                 779

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.177           operator  :=(Tmatrix2__extended):  Tmatrix4__extended

    Synopsis:    Allow  assignment  of  two-dimensional  extended  precision  matrix  to  four-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix4_extended
                                                                                                                (const  v:  Tmatrix*
 *2_extended)
                                                                                                                  :  Tmatrix4_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with single precision is expected.  The extra fields are set to
                0.
                18.3.178           operator  :=(Tmatrix2__extended):  Tmatrix4__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_extended):  Tmatrix4_single
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with single precision is expected.  The extra fields are
                set to 0 and some precision is lost because of the conversion.
                18.3.179           operator  :=(Tmatrix2__single):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with double precision is expected.
                18.3.180           operator  :=(Tmatrix2__single):  Tmatrix2__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix2_s*
 *ingle)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with extended precision is expected.



                                                                                 780

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.181           operator  :=(Tmatrix2__single):  Tmatrix3__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with double precision is expected.  The extra fields are set
                to 0.
                18.3.182           operator  :=(Tmatrix2__single):  Tmatrix3__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix2_s*
 *ingle)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever  a  three-dimensional  matrix  with  extended  precision  is  expected.  The  extra  fields  are
                set to 0.
                18.3.183           operator  :=(Tmatrix2__single):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with single precision is expected.  The extra fields are set to
                0.
                18.3.184           operator  :=(Tmatrix2__single):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with double precision is expected.  The extra fields are set to
                0.



                                                                                 781

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.185           operator  :=(Tmatrix2__single):  Tmatrix4__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix2_s*
 *ingle)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with extended precision is expected.  The extra fields are set
                to 0.
                18.3.186           operator  :=(Tmatrix2__single):  Tmatrix4__single

    Synopsis:    Allow assignment of two-dimensional single precision matrix to four-dimensional single pre-
                cision matrix

Declaration:     function  operator  :=(Tmatrix2_single):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with single precision is expected.  The extra fields are set to
                0.
                18.3.187           operator  :=(Tmatrix3__double):  Tmatrix2__double

    Synopsis:    Allow assignment of three-dimensional double precision matrix to two-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away.
                18.3.188           operator  :=(Tmatrix3__double):  Tmatrix2__extended

    Synopsis:    Allow assignment of three-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix3_d*
 *ouble)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 782

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.189           operator  :=(Tmatrix3__double):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some accuracy is lost because of the conversion.
                18.3.190           operator  :=(Tmatrix3__double):  Tmatrix3__extended

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix3_d*
 *ouble)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with extended precision is expected.
                18.3.191           operator  :=(Tmatrix3__double):  Tmatrix3__single

    Synopsis:    Allow assignment of three-dimensional double precision matrix to three-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.192           operator  :=(Tmatrix3__double):  Tmatrix4__double

    Synopsis:    Allow assignment of three-dimensional double precision matrix to four-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with double precision is expected.



                                                                                 783

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.193           operator  :=(Tmatrix3__double):  Tmatrix4__extended

    Synopsis:    Allow assignment of three-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix3_d*
 *ouble)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with extended precision is expected.
                18.3.194           operator  :=(Tmatrix3__double):  Tmatrix4__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_double):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.195           operator  :=(Tmatrix3__extended):  Tmatrix2__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix2_double
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away and some accuracy is lost becuase of the conversion.
                18.3.196           operator  :=(Tmatrix3__extended):  Tmatrix2__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  matrix  to  two-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix2_extended
                                                                                                                (const  v:  Tmatrix*
 *3_extended)
                                                                                                                  :  Tmatrix2_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 784

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.197           operator  :=(Tmatrix3__extended):  Tmatrix2__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix2_single
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost because of the conversion.
                18.3.198           operator  :=(Tmatrix3__extended):  Tmatrix3__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to three-dimensional dou-
                ble precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix3_double
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever  a  three-dimensional  matrix  with  double  precision  is  expected.  Some  precision  is
                lost because of the conversion.
                18.3.199           operator  :=(Tmatrix3__extended):  Tmatrix3__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix3_single
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.200           operator  :=(Tmatrix3__extended):  Tmatrix4__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix4_double
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with double precision is expected.  Some precision is lost
                because of the conversion.



                                                                                 785

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.201           operator  :=(Tmatrix3__extended):  Tmatrix4__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  matrix  to  four-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix4_extended
                                                                                                                (const  v:  Tmatrix*
 *3_extended)
                                                                                                                  :  Tmatrix4_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with extended precision is expected.
                18.3.202           operator  :=(Tmatrix3__extended):  Tmatrix4__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_extended):  Tmatrix4_single
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.203           operator  :=(Tmatrix3__single):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away.
                18.3.204           operator  :=(Tmatrix3__single):  Tmatrix2__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix3_s*
 *ingle)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 786

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.205           operator  :=(Tmatrix3__single):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away.
                18.3.206           operator  :=(Tmatrix3__single):  Tmatrix3__double

    Synopsis:    Allow assignment of three-dimensional single precision matrix to three-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a three-dimensional matrix with double precision is expected.
                18.3.207           operator  :=(Tmatrix3__single):  Tmatrix3__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix3_s*
 *ingle)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a three-dimensional matrix with extended precision is expected.
                18.3.208           operator  :=(Tmatrix3__single):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a four-dimensional matrix with double precision is expected.

                                                                                 787

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.209           operator  :=(Tmatrix3__single):  Tmatrix4__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix3_s*
 *ingle)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a four-dimensional matrix with extended precision is expected.
                18.3.210           operator  :=(Tmatrix3__single):  Tmatrix4__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix3_single):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a four-dimensional matrix with single precision is expected.
                18.3.211           operator  :=(Tmatrix4__double):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away.
                18.3.212           operator  :=(Tmatrix4__double):  Tmatrix2__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix4_d*
 *ouble)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 788

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.213           operator  :=(Tmatrix4__double):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost in the conversion.
                18.3.214           operator  :=(Tmatrix4__double):  Tmatrix3__double

    Synopsis:    Allow assignment of four-dimensional double precision matrix to three-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with double precision is expected.  The surplus fields
                are thrown away.
                18.3.215           operator  :=(Tmatrix4__double):  Tmatrix3__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to three-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix4_d*
 *ouble)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.
                18.3.216           operator  :=(Tmatrix4__double):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost because of the conversion.



                                                                                 789

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.217           operator  :=(Tmatrix4__double):  Tmatrix4__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix4_d*
 *ouble)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with extended precision is expected.
                18.3.218           operator  :=(Tmatrix4__double):  Tmatrix4__single

    Synopsis:    Allow assignment of four-dimensional single precision matrix to four-dimensional single pre-
                cision matrix

Declaration:     function  operator  :=(Tmatrix4_double):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.219           operator  :=(Tmatrix4__extended):  Tmatrix2__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix2_double
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away and some precision is lost in the conversion.
                18.3.220           operator  :=(Tmatrix4__extended):  Tmatrix2__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  matrix  to  two-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix2_extended
                                                                                                                (const  v:  Tmatrix*
 *4_extended)
                                                                                                                  :  Tmatrix2_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with single precision is expected.  The surplus fields are thrown
                away.



                                                                                 790

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.221           operator  :=(Tmatrix4__extended):  Tmatrix2__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix2_single
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost in the conversion.
                18.3.222           operator  :=(Tmatrix4__extended):  Tmatrix3__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to three-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix3_double
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with double precision is expected.  The surplus fields
                are thrown away.
                18.3.223           operator  :=(Tmatrix4__extended):  Tmatrix3__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix3_extended
                                                                                                                (const  v:  Tmatrix*
 *4_extended)
                                                                                                                  :  Tmatrix3_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with double precision is expected.  The surplus fields
                are thrown away.
                18.3.224           operator  :=(Tmatrix4__extended):  Tmatrix3__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix3_single
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost because of the conversion.



                                                                                 791

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.225           operator  :=(Tmatrix4__extended):  Tmatrix4__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix4_double
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with double precision is expected.
                18.3.226           operator  :=(Tmatrix4__extended):  Tmatrix4__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_extended):  Tmatrix4_single
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.227           operator  :=(Tmatrix4__single):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever  a  two-dimensional  matrix  with  double  precision  is  expected.   The  surplus  fields  are
                thrown away.
                18.3.228           operator  :=(Tmatrix4__single):  Tmatrix2__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix4_s*
 *ingle)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with extended precision is expected.  The surplus fields are
                thrown away.



                                                                                 792

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.229           operator  :=(Tmatrix4__single):  Tmatrix2__single

    Synopsis:    Allow assignment of four-dimensional single precision matrix to two-dimensional single pre-
                cision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with single precision is expected.  The surplus fields are thrown
                away.
                18.3.230           operator  :=(Tmatrix4__single):  Tmatrix3__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  three-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever  a  three-dimensional  matrix  with  double  precision  is  expected.  The  surplus  fields  are
                thrown away.
                18.3.231           operator  :=(Tmatrix4__single):  Tmatrix3__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix4_s*
 *ingle)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with extended precision is expected.  The surplus fields are
                thrown away.
                18.3.232           operator  :=(Tmatrix4__single):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever  a  three-dimensional  matrix  with  single  precision  is  expected.   The  surplus  fields  are
                thrown away.



                                                                                 793

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.233           operator  :=(Tmatrix4__single):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with double precision is expected.
                18.3.234           operator  :=(Tmatrix4__single):  Tmatrix4__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     function  operator  :=(Tmatrix4_single):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix4_s*
 *ingle)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with extended precision is expected.
                18.3.235           operator  :=(Tvector2__double):  Tvector2__extended

    Synopsis:    Allow assignment of double precision vector to extended precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector2_extended
                                                                                                             (const  v:  Tvector2_d*
 *ouble)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a vector with double precision values wherever an extended
                precision vector is expected.
                18.3.236           operator  :=(Tvector2__double):  Tvector2__single

    Synopsis:    Allow assignment of double precision vector to single precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector2_single
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  vector  with  double  precision  values  wherever  a  single
                precision vector is expected, at the cost of loosing some precision.


                                                                                 794

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.237           operator  :=(Tvector2__double):  Tvector3__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector3_double
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever a three-dimensional vector with double precision is expected.  The third dimension is
                set to 0.0.
                18.3.238           operator  :=(Tvector2__double):  Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional double precision vector to three-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector3_extended
                                                                                                             (const  v:  Tvector2_d*
 *ouble)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The third dimension is
                set to 0.0.
                18.3.239           operator  :=(Tvector2__double):  Tvector3__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector3_single
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever  a  three-dimensional  vector  with  single  precision  is  expected.   Some  accuracy  is  lost
                because of the conversion and the third dimension is set to 0.0.
                18.3.240           operator  :=(Tvector2__double):  Tvector4__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector4_double
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever  a  four-dimensional  vector  with  double  precision  is  expected.   The  third  and  fourth
                dimensions are set to 0.0.



                                                                                 795

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.241           operator  :=(Tvector2__double):  Tvector4__extended

    Synopsis:    Allow assignment of two-dimensional double precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector4_extended
                                                                                                             (const  v:  Tvector2_d*
 *ouble)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  extended  precision  is  expected.  The  third  and  fourth
                dimensions are set to 0.0.
                18.3.242           operator  :=(Tvector2__double):  Tvector4__single

    Synopsis:    Allow assignment of two-dimensional double precision vector to four-dimensional single pre-
                cision vector

Declaration:     function  operator  :=(Tvector2_double):  Tvector4_single
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever a four-dimensional vector with single precision is expected.  Some accurace is lost because
                of the conversion and the third and fourth dimensions are set to 0.0.
                18.3.243           operator  :=(Tvector2__extended):  Tvector2__double

    Synopsis:    Allow assignment of extended precision vector to double precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector2_double
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to use a vector with extended precision values wherever a double
                precision vector is expected, at the cost of loosing some precision.
                18.3.244           operator  :=(Tvector2__extended):  Tvector2__single

    Synopsis:    Allow assignment of extended precision vector to single precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector2_single
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to use a vector with extended precision values wherever a single
                precision vector is expected, at the cost of loosing some precision.



                                                                                 796

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.245           operator  :=(Tvector2__extended):  Tvector3__double

    Synopsis:    Allow assignment of two-dimensional extended precision vector to three-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector3_double
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with double precision is expected.  Some accuracy is lost
                because of the conversion and the third dimension is set to 0.0.
                18.3.246           operator  :=(Tvector2__extended):  Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional extened precision vector to three-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector3_extended
                                                                                                                (const  v:  Tvector*
 *2_extended)
                                                                                                                  :  Tvector3_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with extended precision is expected.  The third dimen-
                sion is set to 0.0.
                18.3.247           operator  :=(Tvector2__extended):  Tvector3__single

    Synopsis:    Allow assignment of two-dimensional extended precision vector to three-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector3_single
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion and the third dimension is set to 0.0.
                18.3.248           operator  :=(Tvector2__extended):  Tvector4__double

    Synopsis:    Allow assignment of two-dimensional extended precision vector to four-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector4_double
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with double precision is expected.  Some accuracy is lost
                because of the conversion and the third and fourth dimensions are set to 0.0.



                                                                                 797

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.249           operator  :=(Tvector2__extended):  Tvector4__extended

    Synopsis:    Allow assignment of two-dimensiona extended precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector4_extended
                                                                                                                (const  v:  Tvector*
 *2_extended)
                                                                                                                  :  Tvector4_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with extended precision is expected.  The third and fourth
                dimensions are set to 0.0.
                18.3.250           operator  :=(Tvector2__extended):  Tvector4__single

    Synopsis:    Allow assignment of two-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector2_extended):  Tvector4_single
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion and the third and fourth dimensions are set to 0.0.
                18.3.251           operator  :=(Tvector2__single):  Tvector2__double

    Synopsis:    Allow assignment of single precision vector to double precision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector2_double
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  vector  with  single  precision  values  wherever  a  double
                precision vector is expected.
                18.3.252           operator  :=(Tvector2__single):  Tvector2__extended

    Synopsis:    Allow assignment of single precision vector to extended precision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector2_extended
                                                                                                             (const  v:  Tvector2_s*
 *ingle)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a vector with single precision values wherever an extended
                precision vector is expected.



                                                                                 798

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.253           operator  :=(Tvector2__single):  Tvector3__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector3_double
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever a three-dimensional vector with double precision is expected.  The third dimension is
                set to 0.0.
                18.3.254           operator  :=(Tvector2__single):  Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector3_extended
                                                                                                             (const  v:  Tvector2_s*
 *ingle)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The third dimension is
                set to 0.0.
                18.3.255           operator  :=(Tvector2__single):  Tvector3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector3_single
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever a three-dimensional vector with single precision is expected.  The third dimension is set
                to 0.0.
                18.3.256           operator  :=(Tvector2__single):  Tvector4__double

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional double pre-
                cision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector4_double
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  double  precision  is  expected.   The  third  and  fourth
                dimensions are set to 0.0.



                                                                                 799

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.257           operator  :=(Tvector2__single):  Tvector4__extended

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector4_extended
                                                                                                             (const  v:  Tvector2_s*
 *ingle)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  extended  precision  is  expected.  The  third  and  fourth
                dimensions are set to 0.0.
                18.3.258           operator  :=(Tvector2__single):  Tvector4__single

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional single pre-
                cision vector

Declaration:     function  operator  :=(Tvector2_single):  Tvector4_single
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  single  precision  is  expected.  The  third  and  fourth  di-
                mensions are set to 0.0.
                18.3.259           operator  :=(Tvector3__double):  Tvector2__double

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector2_double
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third dimension
                is thrown away.
                18.3.260           operator  :=(Tvector3__double):  Tvector2__extended

    Synopsis:    Allow assignment of three-dimensional double precision vector to two-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector2_extended
                                                                                                             (const  v:  Tvector3_d*
 *ouble)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with extended precision is expected.  The third dimension
                is thrown away.



                                                                                 800

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.261           operator  :=(Tvector3__double):  Tvector2__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  two-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector2_single
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third dimension is
                thrown away and some precision is lost because of the conversion.
                18.3.262           operator  :=(Tvector3__double):  Tvector3__extended

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  three-dimensional  ex-
                tended precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector3_extended
                                                                                                             (const  v:  Tvector3_d*
 *ouble)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with extended precision is expected.
                18.3.263           operator  :=(Tvector3__double):  Tvector3__single

    Synopsis:    Allow assignment of three-dimensional double precision vector to three-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector3_single
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with single precision is expected.  Some precision is lost
                because of the conversion.
                18.3.264           operator  :=(Tvector3__double):  Tvector4__double

    Synopsis:    Allow assignment of three-dimensional double precision vector to four-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector4_double
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0.



                                                                                 801

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.265           operator  :=(Tvector3__double):  Tvector4__extended

    Synopsis:    Allow assignment of three-dimensional double precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector4_extended
                                                                                                             (const  v:  Tvector3_d*
 *ouble)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with extended precision is expected.  The fourth dimen-
                sion is set to 0.
                18.3.266           operator  :=(Tvector3__double):  Tvector4__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector3_double):  Tvector4_single
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0 and some precision is lost because of the conversion.
                18.3.267           operator  :=(Tvector3__extended):  Tvector2__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to two-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector2_double
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a two-dimensional vector with double precision is expected.  The third dimension
                is thrown away and some precision is lost because of the conversion.
                18.3.268           operator  :=(Tvector3__extended):  Tvector2__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  vector  to  two-dimensional  ex-
                tended precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector2_extended
                                                                                                                (const  v:  Tvector*
 *3_extended)
                                                                                                                  :  Tvector2_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a two-dimensional vector with extended precision is expected.  The third dimension
                is thrown away.



                                                                                 802

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.269           operator  :=(Tvector3__extended):  Tvector2__single

    Synopsis:    Allow assignment of three-dimensional extended precision vector to two-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector2_single
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a two-dimensional vector with single precision is expected.  The third dimension is
                thrown away and some precision is lost because of the conversion.
                18.3.270           operator  :=(Tvector3__extended):  Tvector3__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to three-dimensional dou-
                ble precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector3_double
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever  a  three-dimensional  vector  with  double  precision  is  expected.  Some  precision  is
                lost because of the conversion.
                18.3.271           operator  :=(Tvector3__extended):  Tvector3__single

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector3_single
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever  a  three-dimensional  vector  with  double  precision  is  expected.  Some  precision  is
                lost because of the conversion.
                18.3.272           operator  :=(Tvector3__extended):  Tvector4__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to four-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector4_double
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0 and some accuracy is lost because of the conversion.



                                                                                 803

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.273           operator  :=(Tvector3__extended):  Tvector4__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  vector  to  four-dimensional  ex-
                tended precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector4_extended
                                                                                                                (const  v:  Tvector*
 *3_extended)
                                                                                                                  :  Tvector4_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  extended  precision  val-
                ues  wherever  a  four-dimensional  vector  with  extended  precision  is  expected.   The  fourth
                dimension is set to 0.
                18.3.274           operator  :=(Tvector3__extended):  Tvector4__single

    Synopsis:    Allow assignment of three-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector3_extended):  Tvector4_single
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a four-dimensional vector with single precision is expected.  The fourth dimension
                is set to 0 and some accuracy is lost because of the conversion.
                18.3.275           operator  :=(Tvector3__single):  Tvector2__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector2_double
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third dimension
                is thrown away.
                18.3.276           operator  :=(Tvector3__single):  Tvector2__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to two-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector2_extended
                                                                                                             (const  v:  Tvector3_s*
 *ingle)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a two-dimensional vector with extended precision is expected.  The third dimension
                is thrown away.



                                                                                 804

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.277           operator  :=(Tvector3__single):  Tvector2__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  two-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector2_single
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third dimension is
                thrown away.
                18.3.278           operator  :=(Tvector3__single):  Tvector3__double

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector3_double
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a three-dimensional vector with double precision is expected.
                18.3.279           operator  :=(Tvector3__single):  Tvector3__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector3_extended
                                                                                                             (const  v:  Tvector3_s*
 *ingle)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a three-dimensional vector with extended precision is expected.
                18.3.280           operator  :=(Tvector3__single):  Tvector4__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector4_double
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0.



                                                                                 805

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.281           operator  :=(Tvector3__single):  Tvector4__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector4_extended
                                                                                                             (const  v:  Tvector3_s*
 *ingle)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with single precision values wher-
                ever a four-dimensional vector with extended precision is expected.  The fourth dimension is
                set to 0.
                18.3.282           operator  :=(Tvector3__single):  Tvector4__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector3_single):  Tvector4_single
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a four-dimensional vector with single precision is expected.  The fourth dimension
                is set to 0.
                18.3.283           operator  :=(Tvector4__double):  Tvector2__double

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector2_double
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third and fourth
                dimensions are thrown away.
                18.3.284           operator  :=(Tvector4__double):  Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional double precision vector to two-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector2_extended
                                                                                                             (const  v:  Tvector4_d*
 *ouble)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever  a  two-dimensional  vector  with  extended  precision  is  expected.   The  third  and
                fourth dimensions are thrown away.



                                                                                 806

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.285           operator  :=(Tvector4__double):  Tvector2__single

    Synopsis:    Allow assignment of four-dimensional double precision vector to two-dimensional single pre-
                cision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector2_single
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third and fourth
                dimensions are thrown away and some accuracy is lost because of the conversion.
                18.3.286           operator  :=(Tvector4__double):  Tvector3__double

    Synopsis:    Allow assignment of four-dimensional double precision vector to three-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector3_double
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with double precision is expected.  The fourth dimension
                is thrown away.
                18.3.287           operator  :=(Tvector4__double):  Tvector3__extended

    Synopsis:    Allow assignment of four-dimensional double precision vector to three-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector3_extended
                                                                                                             (const  v:  Tvector4_d*
 *ouble)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with double precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The fourth dimension
                is thrown away.
                18.3.288           operator  :=(Tvector4__double):  Tvector3__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector3_single
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with single precision is expected.  The fourth dimension
                is thrown away and some accuracy is lost because of the conversion.



                                                                                 807

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.289           operator  :=(Tvector4__double):  Tvector4__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector4_extended
                                                                                                             (const  v:  Tvector4_d*
 *ouble)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with extended precision is expected.
                18.3.290           operator  :=(Tvector4__double):  Tvector4__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector4_double):  Tvector4_single
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion.
                18.3.291           operator  :=(Tvector4__extended):  Tvector2__double

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector2_double
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third and fourth
                dimensions are thrown away and some accuracy is lost because of the conversion.
                18.3.292           operator  :=(Tvector4__extended):  Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector2_extended
                                                                                                                (const  v:  Tvector*
 *4_extended)
                                                                                                                  :  Tvector2_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a two-dimensional vector with extended precision is expected.  The third and fourth
                dimensions are thrown away.



                                                                                 808

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.293           operator  :=(Tvector4__extended):  Tvector2__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector2_single
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third and fourth
                dimensions are thrown away and some accuracy is los because of the conversion.
                18.3.294           operator  :=(Tvector4__extended):  Tvector3__double

    Synopsis:    Allow assignment of four-dimensional extended precision vector to three-dimensional double
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector3_double
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with double precision is expected.  The fourth dimension
                is thrown away and some accuracy is lost because of the conversion.
                18.3.295           operator  :=(Tvector4__extended):  Tvector3__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  vector  to  three-dimensional  ex-
                tended precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector3_extended
                                                                                                                (const  v:  Tvector*
 *4_extended)
                                                                                                                  :  Tvector3_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with extended precision is expected.  The fourth dimen-
                sions are thrown away.
                18.3.296           operator  :=(Tvector4__extended):  Tvector3__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to three-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector3_single
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with single precision is expected.  The fourth dimension
                is thrown away and some accuracy is los because of the conversion.



                                                                                 809

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.297           operator  :=(Tvector4__extended):  Tvector4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector4_double
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with double precision is expected.  Some accuracy is lost
                because of the conversion.
                18.3.298           operator  :=(Tvector4__extended):  Tvector4__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     function  operator  :=(Tvector4_extended):  Tvector4_single
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion.
                18.3.299           operator  :=(Tvector4__single):  Tvector2__double

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional double pre-
                cision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector2_double
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever  a  two-dimensional  vector  with  double  precision  is  expected.   The  third  and  fourth
                dimensions are thrown away.
                18.3.300           operator  :=(Tvector4__single):  Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector2_extended
                                                                                                             (const  v:  Tvector4_s*
 *ingle)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever  a  two-dimensional  vector  with  extended  precision  is  expected.  The  third  and  fourth
                dimensions are thrown away.



                                                                                 810

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.301           operator  :=(Tvector4__single):  Tvector2__single

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional single pre-
                cision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector2_single
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a two-dimensional vector with single precision is expected.  The third and fourth dimen-
                sions are thrown away.
                18.3.302           operator  :=(Tvector4__single):  Tvector3__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector3_double
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a three-dimensional vector with double precision is expected.  The fourth dimension is
                thrown away.
                18.3.303           operator  :=(Tvector4__single):  Tvector3__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector3_extended
                                                                                                             (const  v:  Tvector4_s*
 *ingle)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The fourth dimension
                is thrown away.
                18.3.304           operator  :=(Tvector4__single):  Tvector3__single

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector3_single
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a three-dimensional vector with single precision is expected.  The fourth dimension is
                thrown away.



                                                                                 811

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.3.305           operator  :=(Tvector4__single):  Tvector4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector4_double
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a four-dimensional vector with double precision is expected.
                18.3.306           operator  :=(Tvector4__single):  Tvector4__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     function  operator  :=(Tvector4_single):  Tvector4_extended
                                                                                                             (const  v:  Tvector4_s*
 *ingle)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a four-dimensional vector with extended precision is expected.
                18.3.307           operator ><(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     function  operator  ><(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 *  (const  x:  Tvector3_double;
                                                                                                                                   *
 *  const  y:  Tvector3_double)
                                                                                                                                   *
 *    :  Tvector3_double

    Visibility:   default

Description:     This operator returns the external product of two three dimensional vector.  It is a vector
                orthonormal to the two multiplied vectors.  The length of that vector is equal to the surface
                area of a parallelogram with the two vectors as sides.

                The external product is often used to get a vector orthonormal to two other vectors, but of a
                predefined length.  In order to do so, the result vector from the external product, is divided
                by its length, and then multiplied by the desired size.
                18.3.308           operator ><(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:
                                                                                                                                   *
 *            function  operator  ><(Tvector3_extended,  Tvector3_extended):  Tvector3_extended
                                                                                                                                   *
 *            (const  x:  Tvector3_extended;
                                                                                                                                   *
 *            const  y:  Tvector3_extended)
                                                                                                                                   *
 *              :  Tvector3_extended

    Visibility:   default



                                                                                 812

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
Description:     This operator returns the external product of two three dimensional vector.  It is a vector
                orthonormal to the two multiplied vectors.  The length of that vector is equal to the surface
                area of a parallelogram with the two vectors as sides.

                The external product is often used to get a vector orthonormal to two other vectors, but of a
                predefined length.  In order to do so, the result vector from the external product, is divided
                by its length, and then multiplied by the desired size.
                18.3.309           operator ><(Tvector3__single, Tvector3__single):  Tvector3__single

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     function  operator  ><(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 *  (const  x:  Tvector3_single;
                                                                                                                                   *
 *  const  y:  Tvector3_single)
                                                                                                                                   *
 *    :  Tvector3_single

    Visibility:   default

Description:     This operator returns the external product of two three dimensional vector.  It is a vector
                orthonormal to the two multiplied vectors.  The length of that vector is equal to the surface
                area of a parallelogram with the two vectors as sides.

                The external product is often used to get a vector orthonormal to two other vectors, but of a
                predefined length.  In order to do so, the result vector from the external product, is divided
                by its length, and then multiplied by the desired size.
                18.4          Tmatrix2 __double



                18.4.1         Description

                The Tmatrix2_double object provides a matrix of 2*2 double precision scalars.
                18.4.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  815       determinant          Calculates the determinant of the matrix.
                  814       get_column           Returns the c-th column of the matrix as vector.
                  814       get_row              Returns the r-th row of the matrix as vector.
                  814       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  814       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  813       init_zero            Initializes the matrix and sets its elements to zero
                  815       inverse              Calculates the inverse of the matrix.
                  814       set_column           Sets c-th column of the matrix with a vector.
                  814       set_row              Sets r-th row of the matrix with a vector.
                __815_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________
                18.4.3         Tmatrix2__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                 813

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.4.4         Tmatrix2__double.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.4.5         Tmatrix2__double.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  double;ab:  double;ba:  double;bb:  double)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.4.6         Tmatrix2__double.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector2_double

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.4.7         Tmatrix2__double.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector2_double

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.4.8         Tmatrix2__double.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector2_double)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.4.9         Tmatrix2__double.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector2_double)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.



                                                                                 814

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.4.10          Tmatrix2__double.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  double

    Visibility:   default

Description:     Returns the determinant of the matrix.
                18.4.11          Tmatrix2__double.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  double)  :  Tmatrix2_double

    Visibility:   default

Description:     Tmatrix2_double.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass the determinant of the matrix as parameter.
                18.4.12          Tmatrix2__double.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix2_double

    Visibility:   default

Description:     Tmatrix2_double.transpose  returns  a  new  matrix  that  is  the  transposition  of  the  matrix,
                that is, the matrix with the x and y coordinates of the values swapped.
                18.5          Tmatrix2 __extended



                18.5.1         Description

                The Tmatrix2_extended object provides a matrix of 2*2 extended precision scalars.
                18.5.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  817       determinant          Calculates the determinant of the matrix.
                  816       get_column           Returns the c-th column of the matrix as vector.
                  816       get_row              Returns the r-th row of the matrix as vector.
                  816       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  816       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  816       init_zero            Initializes the matrix and sets its elements to zero
                  817       inverse              Calculates the inverse of the matrix.
                  816       set_column           Sets c-th column of the matrix with a vector.
                  817       set_row              Sets r-th row of the matrix with a vector.
                __817_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________

                                                                                 815

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.5.3         Tmatrix2__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.5.4         Tmatrix2__extended.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.5.5         Tmatrix2__extended.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  extended;ab:  extended;ba:  extended;bb:  extended)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.5.6         Tmatrix2__extended.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector2_extended

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.5.7         Tmatrix2__extended.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector2_extended

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.5.8         Tmatrix2__extended.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector2_extended)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.



                                                                                 816

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.5.9         Tmatrix2__extended.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector2_extended)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.
                18.5.10          Tmatrix2__extended.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  extended

    Visibility:   default

Description:     Returns the determinant of the matrix.
                18.5.11          Tmatrix2__extended.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  extended)  :  Tmatrix2_extended

    Visibility:   default

Description:     Tmatrix2_extended.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass the determinant of the matrix as parameter.
                18.5.12          Tmatrix2__extended.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix2_extended

    Visibility:   default

Description:     Tmatrix2_extended.transpose returns a new matrix that is the transposition of the matrix,
                that is, the matrix with the x and y coordinates of the values swapped.
                18.6          Tmatrix2 __single



                18.6.1         Description

                The Tmatrix2_single object provides a matrix of 2*2 single precision scalars.



                                                                                 817

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.6.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  819       determinant          Calculates the determinant of the matrix.
                  818       get_column           Returns the c-th column of the matrix as vector.
                  819       get_row              Returns the r-th row of the matrix as vector.
                  818       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  818       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  818       init_zero            Initializes the matrix and sets its elements to zero
                  819       inverse              Calculates the inverse of the matrix.
                  819       set_column           Sets c-th column of the matrix with a vector.
                  819       set_row              Sets r-th row of the matrix with a vector.
                __819_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________
                18.6.3         Tmatrix2__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.6.4         Tmatrix2__single.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.6.5         Tmatrix2__single.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  single;ab:  single;ba:  single;bb:  single)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.6.6         Tmatrix2__single.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector2_single

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.



                                                                                 818

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.6.7         Tmatrix2__single.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector2_single

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.6.8         Tmatrix2__single.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector2_single)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.6.9         Tmatrix2__single.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector2_single)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.
                18.6.10          Tmatrix2__single.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  single

    Visibility:   default

Description:     Returns the determinant of the matrix.
                18.6.11          Tmatrix2__single.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  single)  :  Tmatrix2_single

    Visibility:   default

Description:     Tmatrix2_single.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass the determinant of the matrix as parameter.
                18.6.12          Tmatrix2__single.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix2_single

    Visibility:   default

Description:     Tmatrix2_single.transpose returns a new matrix that is the transposition of the matrix, that
                is, the matrix with the x and y coordinates of the values swapped.



                                                                                 819

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.7          Tmatrix3 __double



                18.7.1         Description

                The Tmatrix3_double object provides a matrix of 3*3 double precision scalars.
                18.7.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  821       determinant          Calculates the determinant of the matrix.
                  821       get_column           Returns the c-th column of the matrix as vector.
                  821       get_row              Returns the r-th row of the matrix as vector.
                  820       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  820       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  820       init_zero            Initializes the matrix and sets its elements to zero
                  821       inverse              Calculates the inverse of the matrix.
                  821       set_column           Sets c-th column of the matrix with a vector.
                  821       set_row              Sets r-th row of the matrix with a vector.
                __822_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________
                18.7.3         Tmatrix3__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.7.4         Tmatrix3__double.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.7.5         Tmatrix3__double.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  double;ab:  double;ac:  double;ba:  double;bb:  double;
                                           bc:  double;ca:  double;cb:  double;cc:  double)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.


                                                                                 820

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.7.6         Tmatrix3__double.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector3_double

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.7.7         Tmatrix3__double.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector3_double

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.7.8         Tmatrix3__double.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector3_double)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.7.9         Tmatrix3__double.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector3_double)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.
                18.7.10          Tmatrix3__double.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  double

    Visibility:   default

Description:     Returns the determinant of the matrix.
                18.7.11          Tmatrix3__double.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  double)  :  Tmatrix3_double

    Visibility:   default

Description:     Tmatrix3_double.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass the determinant of the matrix as parameter.



                                                                                 821

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.7.12          Tmatrix3__double.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix3_double

    Visibility:   default

Description:     Tmatrix2_double.transpose  returns  a  new  matrix  that  is  the  transposition  of  the  matrix,
                that is, the matrix with the x and y coordinates of the values swapped.
                18.8          Tmatrix3 __extended



                18.8.1         Description

                The Tmatrix3_extended object provides a matrix of 3*3 extended precision scalars.
                18.8.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  824       determinant          Calculates the determinant of the matrix.
                  823       get_column           Returns the c-th column of the matrix as vector.
                  823       get_row              Returns the r-th row of the matrix as vector.
                  823       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  822       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  822       init_zero            Initializes the matrix and sets its elements to zero
                  824       inverse              Calculates the inverse of the matrix.
                  823       set_column           Sets r-th column of the matrix with a vector.
                  823       set_row              Sets r-th row of the matrix with a vector.
                __824_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________
                18.8.3         Tmatrix3__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.8.4         Tmatrix3__extended.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                                                                                 822

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.8.5         Tmatrix3__extended.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  extended;ab:  extended;ac:  extended;ba:  extended;
                                           bb:  extended;bc:  extended;ca:  extended;cb:  extended;
                                           cc:  extended)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.8.6         Tmatrix3__extended.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector3_extended

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.8.7         Tmatrix3__extended.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector3_extended

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.8.8         Tmatrix3__extended.set__column

    Synopsis:    Sets r-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector3_extended)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.8.9         Tmatrix3__extended.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector3_extended)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.

                                                                                 823

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.8.10          Tmatrix3__extended.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  extended

    Visibility:   default

Description:     Returns the determinant of the matrix.
                18.8.11          Tmatrix3__extended.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  extended)  :  Tmatrix3_extended

    Visibility:   default

Description:     Tmatrix3_extended.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass the determinant of the matrix as parameter.
                18.8.12          Tmatrix3__extended.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix3_extended

    Visibility:   default

Description:     Tmatrix2_extended.transpose returns a new matrix that is the transposition of the matrix,
                that is, the matrix with the x and y coordinates of the values swapped.
                18.9          Tmatrix3 __single



                18.9.1         Description

                The Tmatrix3_single object provides a matrix of 3*3 single precision scalars.
                18.9.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  826       determinant          Calculates the determinant of the matrix.
                  825       get_column           Returns the c-th column of the matrix as vector.
                  825       get_row              Returns the r-th row of the matrix as vector.
                  825       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  825       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  825       init_zero            Initializes the matrix and sets its elements to zero
                  826       inverse              Calculates the inverse of the matrix.
                  825       set_column           Sets c-th column of the matrix with a vector.
                  826       set_row              Sets r-th row of the matrix with a vector.
                __826_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________

                                                                                 824

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.9.3         Tmatrix3__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.9.4         Tmatrix3__single.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.9.5         Tmatrix3__single.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  single;ab:  single;ac:  single;ba:  single;bb:  single;
                                           bc:  single;ca:  single;cb:  single;cc:  single)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.9.6         Tmatrix3__single.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector3_single

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.9.7         Tmatrix3__single.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector3_single

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.9.8         Tmatrix3__single.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector3_single)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.



                                                                                 825

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.9.9         Tmatrix3__single.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector3_single)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.
                18.9.10          Tmatrix3__single.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  single

    Visibility:   default

Description:     Returns the determinant of the matrix.
                18.9.11          Tmatrix3__single.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  single)  :  Tmatrix3_single

    Visibility:   default

Description:     Tmatrix3_single.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass the determinant of the matrix as parameter.
                18.9.12          Tmatrix3__single.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix3_single

    Visibility:   default

Description:     Tmatrix2_single.transpose returns a new matrix that is the transposition of the matrix, that
                is, the matrix with the x and y coordinates of the values swapped.
                18.10            Tmatrix4 __double



                18.10.1          Description

                The Tmatrix4_double object provides a matrix of 4*4 double precision scalars.



                                                                                 826

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.10.2          Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  828       determinant          Calculates the determinant of the matrix.
                  827       get_column           Returns the c-th column of the matrix as vector.
                  828       get_row              Returns the r-th row of the matrix as vector.
                  827       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  827       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  827       init_zero            Initializes the matrix and sets its elements to zero
                  828       inverse              Calculates the inverse of the matrix.
                  828       set_column           Sets c-th column of the matrix with a vector.
                  828       set_row              Sets r-th row of the matrix with a vector.
                __829_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________
                18.10.3          Tmatrix4__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.10.4          Tmatrix4__double.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.10.5          Tmatrix4__double.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  double;ab:  double;ac:  double;ad:  double;ba:  double;
                                           bb:  double;bc:  double;bd:  double;ca:  double;cb:  double;
                                           cc:  double;cd:  double;da:  double;db:  double;dc:  double;
                                           dd:  double)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.10.6          Tmatrix4__double.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector4_double

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.



                                                                                 827

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.10.7          Tmatrix4__double.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector4_double

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.10.8          Tmatrix4__double.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector4_double)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.10.9          Tmatrix4__double.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector4_double)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.
                18.10.10           Tmatrix4__double.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  double

    Visibility:   default

Description:     Returns the determinant of the matrix.  Note:  Calculating the determinant of a 4*4 matrix
                requires quite a few operations.
                18.10.11           Tmatrix4__double.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  double)  :  Tmatrix4_double

    Visibility:   default

Description:     Tmatrix4_double.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass  the  determinant  of  the  matrix  as  parameter.  Note:  Calculating  the  inverse  of  a  4*4
                matrix requires quite a few operations.

                                                                                 828

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.10.12           Tmatrix4__double.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix4_double

    Visibility:   default

Description:     Tmatrix2_double.transpose  returns  a  new  matrix  that  is  the  transposition  of  the  matrix,
                that is, the matrix with the x and y coordinates of the values swapped.
                18.11            Tmatrix4 __extended



                18.11.1          Description

                The Tmatrix4_extended object provides a matrix of 4*4 extended precision scalars.
                18.11.2          Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  831       determinant          Calculates the determinant of the matrix.
                  830       get_column           Returns the c-th column of the matrix as vector.
                  830       get_row              Returns the r-th row of the matrix as vector.
                  830       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  829       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  829       init_zero            Initializes the matrix and sets its elements to zero
                  831       inverse              Calculates the inverse of the matrix.
                  830       set_column           Sets c-th column of the matrix with a vector.
                  830       set_row              Sets r-th row of the matrix with a vector.
                __831_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________
                18.11.3          Tmatrix4__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.11.4          Tmatrix4__extended.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                                                                                 829

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.11.5          Tmatrix4__extended.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  extended;ab:  extended;ac:  extended;ad:  extended;
                                           ba:  extended;bb:  extended;bc:  extended;bd:  extended;
                                           ca:  extended;cb:  extended;cc:  extended;cd:  extended;
                                           da:  extended;db:  extended;dc:  extended;dd:  extended)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.11.6          Tmatrix4__extended.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector4_extended

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.11.7          Tmatrix4__extended.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector4_extended

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                18.11.8          Tmatrix4__extended.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector4_extended)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.11.9          Tmatrix4__extended.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector4_extended)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.



                                                                                 830

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.11.10           Tmatrix4__extended.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  extended

    Visibility:   default

Description:     Returns the determinant of the matrix.  Note:  Calculating the determinant of a 4*4 matrix
                requires quite a few operations.
                18.11.11           Tmatrix4__extended.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  extended)  :  Tmatrix4_extended

    Visibility:   default

Description:     Tmatrix4_extended.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass  the  determinant  of  the  matrix  as  parameter.  Note:  Calculating  the  inverse  of  a  4*4
                matrix requires quite a few operations.
                18.11.12           Tmatrix4__extended.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix4_extended

    Visibility:   default

Description:     Tmatrix2_extended.transpose returns a new matrix that is the transposition of the matrix,
                that is, the matrix with the x and y coordinates of the values swapped.
                18.12            Tmatrix4 __single



                18.12.1          Description

                The Tmatrix4_single object provides a matrix of 4*4 single precision scalars.
                18.12.2          Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  833       determinant          Calculates the determinant of the matrix.
                  832       get_column           Returns the c-th column of the matrix as vector.
                  832       get_row              Returns the r-th row of the matrix as vector.
                  832       init                 Initializes the matrix, setting its elements to the values passed to
                                                 the constructor.
                  832       init_identity        Initializes the matrix and sets its elements to the identity matrix.
                  832       init_zero            Initializes the matrix and sets its elements to zero
                  833       inverse              Calculates the inverse of the matrix.
                  833       set_column           Sets c-th column of the matrix with a vector.
                  833       set_row              Sets r-th row of the matrix with a vector.
                __833_______transpose____________Returns_the_transposition_of_the_matrix.__________________________________________*
 *___________

                                                                                 831

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.12.3          Tmatrix4__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.12.4          Tmatrix4__single.init__identity

    Synopsis:    Initializes the matrix and sets its elements to the identity matrix.

Declaration:     constructor  init_identity

    Visibility:   default

Description:     Initializes the matrix and sets its elements to the identity matrix, that is, elements to 1 on
                the left-upper to right-lower diagonal, the rest zero.
                18.12.5          Tmatrix4__single.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  single;ab:  single;ac:  single;ad:  single;ba:  single;
                                           bb:  single;bc:  single;bd:  single;ca:  single;cb:  single;
                                           cc:  single;cd:  single;da:  single;db:  single;dc:  single;
                                           dd:  single)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.
                18.12.6          Tmatrix4__single.get__column

    Synopsis:    Returns the c-th column of the matrix as vector.

Declaration:     function  get_column(c:  Byte)  :  Tvector4_single

    Visibility:   default

Description:     Returns the c-th column of the matrix as vector.  The column numbering starts at 0.
                18.12.7          Tmatrix4__single.get__row

    Synopsis:    Returns the r-th row of the matrix as vector.

Declaration:     function  get_row(r:  Byte)  :  Tvector4_single

    Visibility:   default

Description:     Returns the r-th row of the matrix as vector.  The row numbering starts at 0.
                                                                                 832

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.12.8          Tmatrix4__single.set__column

    Synopsis:    Sets c-th column of the matrix with a vector.

Declaration:     procedure  set_column(c:  Byte;const  v:  Tvector4_single)

    Visibility:   default

Description:     Replaces the c-th column of the matrix with vector v.  The column numbering starts at 0.
                18.12.9          Tmatrix4__single.set__row

    Synopsis:    Sets r-th row of the matrix with a vector.

Declaration:     procedure  set_row(r:  Byte;const  v:  Tvector4_single)

    Visibility:   default

Description:     Replaces the r-th row of the matrix with vector v.  The row numbering starts at 0.
                18.12.10           Tmatrix4__single.determinant

    Synopsis:    Calculates the determinant of the matrix.

Declaration:     function  determinant  :  single

    Visibility:   default

Description:     Returns the determinant of the matrix.  Note:  Calculating the determinant of a 4*4 matrix
                requires quite a few operations.
                18.12.11           Tmatrix4__single.inverse

    Synopsis:    Calculates the inverse of the matrix.

Declaration:     function  inverse(Adeterminant:  single)  :  Tmatrix4_single

    Visibility:   default

Description:     Tmatrix4_single.inverse returns a new matrix that is the inverse of the matrix.  You must
                pass  the  determinant  of  the  matrix  as  parameter.  Note:  Calculating  the  inverse  of  a  4*4
                matrix requires quite a few operations.
                18.12.12           Tmatrix4__single.transpose

    Synopsis:    Returns the transposition of the matrix.

Declaration:     function  transpose  :  Tmatrix4_single

    Visibility:   default

Description:     Tmatrix2_single.transpose returns a new matrix that is the transposition of the matrix, that
                is, the matrix with the x and y coordinates of the values swapped.



                                                                                 833

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.13            Tvector2 __double



                18.13.1          Description

                The Tvector2_double object provides a vector of two double precision scalars.
                18.13.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  834       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  834       init_one                 Initializes the vector and sets its elements to one
                  834       init_zero                Initializes the vector and sets its elements to zero
                  834       length                   Calculates the length of the vector.
                __835_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.13.3          Tvector2__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.13.4          Tvector2__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.13.5          Tvector2__double.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  double;b:  double)

    Visibility:   default
                18.13.6          Tvector2__double.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  double

    Visibility:   default

Description:     Calculate the length of the vector: length=sqrt(data[0]**2+data[1]**2).  Try to use squared_length
                (835  ) if you are able to, as it is faster.
                                                                                 834

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.13.7          Tvector2__double.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  double

    Visibility:   default

Description:     Calculate the squared length of the vector:  squared_length=data[0]**2+data[1]**2.
                18.14            Tvector2 __extended



                18.14.1          Description

                The Tvector2_extended object provides a vector of two extended precision scalars.
                18.14.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  835       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  835       init_one                 Initializes the vector and sets its elements to one
                  835       init_zero                Initializes the vector and sets its elements to zero
                  836       length                   Calculates the length of the vector.
                __836_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.14.3          Tvector2__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.14.4          Tvector2__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.14.5          Tvector2__extended.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  extended;b:  extended)

    Visibility:   default

                                                                                 835

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.14.6          Tvector2__extended.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  extended

    Visibility:   default

Description:     Calculate the length of the vector: length=sqrt(data[0]**2+data[1]**2).  Try to use squared_length
                (836  ) if you are able to, as it is faster.
                18.14.7          Tvector2__extended.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  extended

    Visibility:   default

Description:     Calculate the squared length of the vector:  squared_length=data[0]**2+data[1]**2.
                18.15            Tvector2 __single



                18.15.1          Description

                The Tvector2_single object provides a vector of two single precision scalars.
                18.15.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  837       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  836       init_one                 Initializes the vector and sets its elements to one
                  836       init_zero                Initializes the vector and sets its elements to zero
                  837       length                   Calculates the length of the vector.
                __837_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.15.3          Tvector2__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.15.4          Tvector2__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default

                                                                                 836

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.15.5          Tvector2__single.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  single;b:  single)

    Visibility:   default
                18.15.6          Tvector2__single.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  single

    Visibility:   default

Description:     Calculate the length of the vector: length=sqrt(data[0]**2+data[1]**2).  Try to use squared_length
                (837  ) if you are able to, as it is faster.
                18.15.7          Tvector2__single.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  single

    Visibility:   default

Description:     Calculate the squared length of the vector:  squared_length=data[0]**2+data[1]**2.
                18.16            Tvector3 __double



                18.16.1          Description

                The Tvector3_double object provides a vector of three double precision scalars.
                18.16.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  838       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  838       init_one                 Initializes the vector and sets its elements to one
                  837       init_zero                Initializes the vector and sets its elements to zero
                  838       length                   Calculates the length of the vector.
                __838_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.16.3          Tvector3__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default

                                                                                 837

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.16.4          Tvector3__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.16.5          Tvector3__double.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  double;b:  double;c:  double)

    Visibility:   default
                18.16.6          Tvector3__double.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  double

    Visibility:   default

Description:     Calculate the length of the vector:  length=sqrt(data[0]**2+data[1]**2+data[2]**2).  Try to
                use squared_length (838  ) if you are able to, as it is faster.
                18.16.7          Tvector3__double.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  double

    Visibility:   default

Description:     Calculate the squared length of the vector: squared_length=data[0]**2+data[1]**2+data[2]**2.
                18.17            Tvector3 __extended



                18.17.1          Description

                The Tvector3_extended object provides a vector of three extended precision scalars.
                18.17.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  839       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  839       init_one                 Initializes the vector and sets its elements to one
                  839       init_zero                Initializes the vector and sets its elements to zero
                  839       length                   Calculates the length of the vector.
                __839_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________

                                                                                 838

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.17.3          Tvector3__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.17.4          Tvector3__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.17.5          Tvector3__extended.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  extended;b:  extended;c:  extended)

    Visibility:   default
                18.17.6          Tvector3__extended.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  extended

    Visibility:   default

Description:     Calculate the length of the vector:  length=sqrt(data[0]**2+data[1]**2+data[2]**2).  Try to
                use squared_length (839  ) if you are able to, as it is faster.
                18.17.7          Tvector3__extended.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  extended

    Visibility:   default

Description:     Calculate the squared length of the vector: squared_length=data[0]**2+data[1]**2+data[2]**2.
                18.18            Tvector3 __single



                18.18.1          Description

                The Tvector3_single object provides a vector of three single precision scalars.

                                                                                 839

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.18.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  840       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  840       init_one                 Initializes the vector and sets its elements to one
                  840       init_zero                Initializes the vector and sets its elements to zero
                  840       length                   Calculates the length of the vector.
                __840_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.18.3          Tvector3__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.18.4          Tvector3__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.18.5          Tvector3__single.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  single;b:  single;c:  single)

    Visibility:   default
                18.18.6          Tvector3__single.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  single

    Visibility:   default

Description:     Calculate the length of the vector:  length=sqrt(data[0]**2+data[1]**2+data[2]**2).  Try to
                use squared_length (840  ) if you are able to, as it is faster.
                18.18.7          Tvector3__single.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  single

    Visibility:   default

Description:     Calculate the squared length of the vector: squared_length=data[0]**2+data[1]**2+data[2]**2.



                                                                                 840

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.19            Tvector4 __double



                18.19.1          Description

                The Tvector4_double object provides a vector of four double precision scalars.
                18.19.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  841       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  841       init_one                 Initializes the vector and sets its elements to one
                  841       init_zero                Initializes the vector and sets its elements to zero
                  841       length                   Calculates the length of the vector.
                __842_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.19.3          Tvector4__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.19.4          Tvector4__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.19.5          Tvector4__double.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  double;b:  double;c:  double;d:  double)

    Visibility:   default
                18.19.6          Tvector4__double.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  double

    Visibility:   default

Description:     Calculate the length of the vector: length=sqrt(data[0]**2+data[1]**2+data[2]**2+data[3]**2).
                Try to use squared_length (842  ) if you are able to, as it is faster.
                                                                                 841

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.19.7          Tvector4__double.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  double

    Visibility:   default

Description:     Calculate the squared length of the vector: squared_length=data[0]**2+data[1]**2+data[2]**2+data[3]**2.
                18.20            Tvector4 __extended



                18.20.1          Description

                The Tvector4_extended object provides a vector of four extended precision scalars.
                18.20.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  842       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  842       init_one                 Initializes the vector and sets its elements to one
                  842       init_zero                Initializes the vector and sets its elements to zero
                  843       length                   Calculates the length of the vector.
                __843_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.20.3          Tvector4__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.20.4          Tvector4__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default
                18.20.5          Tvector4__extended.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  extended;b:  extended;c:  extended;d:  extended)

    Visibility:   default

                                                                                 842

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.20.6          Tvector4__extended.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  extended

    Visibility:   default

Description:     Calculate the length of the vector: length=sqrt(data[0]**2+data[1]**2+data[2]**2+data[3]**2).
                Try to use squared_length (843  ) if you are able to, as it is faster.
                18.20.7          Tvector4__extended.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  extended

    Visibility:   default

Description:     Calculate the squared length of the vector: squared_length=data[0]**2+data[1]**2+data[2]**2+data[3]**2.
                18.21            Tvector4 __single



                18.21.1          Description

                The Tvector4_single object provides a vector of four single precision scalars.
                18.21.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  844       init                     Initializes the vector, setting its elements to the values passed to
                                                     the constructor.
                  843       init_one                 Initializes the vector and sets its elements to one
                  843       init_zero                Initializes the vector and sets its elements to zero
                  844       length                   Calculates the length of the vector.
                __844_______squared_length___________Calculates_the_squared_length_of_the_vector.__________________________________*
 *___________
                18.21.3          Tvector4__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default
                18.21.4          Tvector4__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default

                                                                                 843

                __________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________
                18.21.5          Tvector4__single.init

    Synopsis:    Initializes the vector, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(a:  single;b:  single;c:  single;d:  single)

    Visibility:   default
                18.21.6          Tvector4__single.length

    Synopsis:    Calculates the length of the vector.

Declaration:     function  length  :  single

    Visibility:   default

Description:     Calculate the length of the vector: length=sqrt(data[0]**2+data[1]**2+data[2]**2+data[3]**2).
                Try to use squared_length (844  ) if you are able to, as it is faster.
                18.21.7          Tvector4__single.squared__length

    Synopsis:    Calculates the squared length of the vector.

Declaration:     function  squared_length  :  single

    Visibility:   default

Description:     Calculate the squared length of the vector: squared_length=data[0]**2+data[1]**2+data[2]**2+data[3]**2.
                                                                                 844


Chapter   19


Reference   for   unit   'mmx'
19.1          Overview


This  document  describes  the  MMX  unit.  This  unit  allows  you  to  use  the  MMX  capabilities
of the Free Pascal compiler.  It was written by Florian Klaempfl for the I386 processor.  It
should work on all platforms that use the Intel processor.
19.2          Constants,  types  and  variables



19.2.1         Constants

is_amd_3d_cpu  :  Boolean  =  false


The  is_amd_3d_cpu  initialized  constant  allows  you  to  determine  if  the  computer  has  the
AMD 3D extensions.  It is set correctly in the unit's initialization code.


is_amd_3d_dsp_cpu  :  Boolean  =  false


The is_amd_3d_dsp_cpu initialized constant allows you to determine if the computer has the
AMD 3D DSP extensions.  It is set correctly in the unit's initialization code.


is_amd_3d_mmx_cpu  :  Boolean  =  false


The is_amd_3d_mmx_cpu initialized constant allows you to determine if the computer has the
AMD 3D MMX extensions.  It is set correctly in the unit's initialization code.


is_mmx_cpu  :  Boolean  =  false


The is_mmx_cpu initialized constant allows you to determine if the computer has MMX exten-
sions.  It is set correctly in the unit's initialization code.


is_sse2_cpu  :  Boolean  =  false


The is_sse2_cpu initialized constant allows you to determine if the computer has the SSE2
extensions.  It is set correctly in the unit's initialization code.


is_sse_cpu  :  Boolean  =  false


The  is_sse_cpu  initialized  constant  allows  you  to  determine  if  the  computer  has  the  SSE
extensions.  It is set correctly in the unit's initialization code.



                                                             845

_______________________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'MMX'______________________________*
 *___
19.2.2         Types

pmmxbyte  =  ^tmmxbyte


Pointer to tmmxbyte (846  ) array type


pmmxcardinal  =  ^tmmxcardinal


Pointer to tmmxcardinal (846  ) array type


pmmxinteger  =  ^tmmxinteger


Pointer to tmmxinteger (846  ) array type


pmmxlongint  =  ^tmmxlongint


Pointer to tmmxlongint (846  ) array type


pmmxshortint  =  ^tmmxshortint


Pointer to tmmxshortint (846  ) array type


pmmxsingle  =  ^tmmxsingle


Pointer to tmmxsingle (846  ) array type


pmmxword  =  ^tmmxword


Pointer to tmmxword (846  ) array type


tmmxbyte  =  Array[0..7]  of  Byte


Array of bytes, 64 bits in size


tmmxcardinal  =  Array[0..1]  of  cardinal


Array of cardinals, 64 bits in size


tmmxinteger  =  Array[0..3]  of  Integer


Array of integers, 64 bits in size


tmmxlongint  =  Array[0..1]  of  LongInt


Array of longint, 64 bits in size


tmmxshortint  =  Array[0..7]  of  ShortInt


Array of shortints, 64 bits in size


tmmxsingle  =  Array[0..1]  of  single


Array of singles, 64 bits in size


tmmxword  =  Array[0..3]  of  Word


Array of words, 64 bits in size



                                                                 846

                _______________________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'MMX'______________*
 *___________________
                19.3          Procedures  and  functions



                19.3.1         emms

    Synopsis:    Reset floating point registers

Declaration:     procedure  emms

    Visibility:   default

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.  The following code demonstrates this:


                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.


    See also:    femms (847  )
                19.3.2         femms

    Synopsis:    Reset floating point registers - AMD version

Declaration:     procedure  femms

    Visibility:   default

Description:     femms executes the femms assembler instruction for AMD processors.  it is not supported by
                all assemblers, hence it is coded as byte codes.

    See also:    emms (847  )


                                                                                 847


Chapter   20


Reference   for   unit   'Mouse'
20.1          Writing  a  custom  mouse  driver


The  mouse  unit  has  support  for  adding  a  custom  mouse  driver.  This  can  be  used  to  add
support for mouses not supported by the standard Free Pascal driver, but also to enhance
an existing driver for instance to log mouse events or to implement a record and playback
function.

The  following  unit  shows  how  a  mouse  driver  can  be  enhanced  by  adding  some  logging
capabilities to the driver.
20.2          Overview


The Mouse unit implements a platform independent mouse handling interface.  It is imple-
mented  identically  on  all  platforms  supported  by  Free  Pascal  and  can  be  enhanced  with
custom drivers, should this be needed.  It is intended to be used only in text-based screens,
for  instance  in  conjunction  with  the  keyboard  and  video  unit.   No  support  for  graphical
screens is implemented, and there are (currently) no plans to implement this.
20.3          Constants,  types  and  variables



20.3.1         Constants

errMouseBase  =  1030


Base for mouse error codes.


errMouseInitError  =  errMouseBase  +  0


Mouse initialization error


errMouseNotImplemented  =  errMouseBase  +  1


Mouse driver not implemented.


MouseActionDown  =  $0001



                                                             848

___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________________________*
 *___
Mouse button down event signal.


MouseActionMove  =  $0004


Mouse cursor move event signal.


MouseActionUp  =  $0002


Mouse button up event signal.


MouseEventBufSize  =  16


The mouse unit has a mechanism to buffer mouse events.  This constant defines the size of
the event buffer.


MouseLeftButton  =  $01


Left mouse button event.


MouseMiddleButton  =  $04


Middle mouse button event.


MouseRightButton  =  $02


Right mouse button event.
20.3.2         Types

PMouseEvent  =  ^TMouseEvent


Pointer to TMouseEvent (850  ) record.


TMouseDriver  =  record
    UseDefaultQueue  :  Boolean;
    InitDriver  :  procedure;
    DoneDriver  :  procedure;
    DetectMouse  :  function  :  Byte;
    ShowMouse  :  procedure;
    HideMouse  :  procedure;
    GetMouseX  :  function  :  Word;
    GetMouseY  :  function  :  Word;
    GetMouseButtons  :  function  :  Word;
    SetMouseXY  :  procedure(x:  Word;y:  Word);
    GetMouseEvent  :  procedure(var  MouseEvent:  TMouseEvent);
    PollMouseEvent  :  function(var  MouseEvent:  TMouseEvent)  :  Boolean;
    PutMouseEvent  :  procedure(const  MouseEvent:  TMouseEvent);
end
The TMouseDriver record is used to implement a mouse driver in the SetMouseDriver (855  )
function.  Its fields must be filled in before calling the SetMouseDriver (855  ) function.



                                                                 849

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
                TMouseEvent  =  packed  record
                   buttons  :  Word;
                   x  :  Word;
                   y  :  Word;
                   Action  :  Word;
                end
                The  TMouseEvent  is  the  central  type  of  the  mouse  unit,  it  is  used  to  describe  all  mouse
                events.

                The  Buttons  field  describes  which  buttons  were  down  when  the  event  occurred.  The  x,y
                fields describe where the event occurred on the screen.  The Action describes what action
                was  going  on  when  the  event  occurred.   The  Buttons  and  Action  field  can  be  examined
                using the constants defined in the unit interface.
                20.3.3         Variables

                MouseButtons  :  Byte


                This variable keeps track of the last known mouse button state.  Do not use.


                MouseIntFlag  :  Byte


                This variable keeps track of the last known internal mouse state.  Do not use.


                MouseWhereX  :  Word


                This variable keeps track of the last known cursor position.  Do not use.


                MouseWhereY  :  Word


                This variable keeps track of the last known cursor position.  Do not use.
                20.4          Procedures  and  functions



                20.4.1         DetectMouse

    Synopsis:    Detect the presence of a mouse.

Declaration:     function  DetectMouse  :  Byte

    Visibility:   default

Description:     DetectMouse  detects  whether  a  mouse  is  attached  to  the  system  or  not.   If  there  is  no
                mouse, then zero is returned.  If a mouse is attached, then the number of mouse buttons is
                returnead.

                This function should be called after the mouse driver was initialized.

       Errors:   None.

    See also:    InitMouse (854  ), DoneMouse (851  )


                Listing:  ./mouseex/ex1.pp



                                                                                 850

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  d e m o n s t r a t et h e  D e t e c t M o u s ef u n c t i o n. }


                Uses     mouse    ;


                Var
                    B u t t o n s :  B y t e ;


                 b e g i n
                    I n i t M o u s e;
                    B u t t o n s:= D e t e c t M o u s;e
                    I f  B u t t o n s=0   then
                        W r i t e l n('No   mouse      p r e s e n t.' )
                    e l s e
                        W r i t e l n('Found      mouse     w i t h  ' ,B u t t o n s, '  b u t t o n s.' ) ;
                    DoneMouse       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                20.4.2         DoneMouse

    Synopsis:    Deinitialize mouse driver.

Declaration:     procedure  DoneMouse

    Visibility:   default

Description:     DoneMouse  De-initializes  the  mouse  driver.  It  cleans  up  any  memory  allocated  when  the
                mouse was initialized, or removes possible mouse hooks from memory.  The mouse functions
                will not work after DoneMouse was called.  If  DoneMouse is called a second time, it will exit
                at once.  InitMouse should be called before DoneMouse can be called again.

                For an example, see most other mouse functions.

       Errors:   None.

    See also:    DetectMouse (850  ), InitMouse (854  )
                20.4.3         GetMouseButtons

    Synopsis:    Get the state of the mouse buttons

Declaration:     function  GetMouseButtons  :  Word

    Visibility:   default

Description:     GetMouseButtons  returns  the  current  button  state  of  the  mouse,  i.e.   it  returns  a  or-ed
                combination of the following constants:


                MouseLeftButton             When the left mouse button is held down.

                MouseRightButton               When the right mouse button is held down.

                MouseMiddleButton                When the middle mouse button is held down.


       Errors:   None.

    See also:    GetMouseEvent (852  ), GetMouseX (853  ), GetMouseY (853  )
                                                                                 851

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
                Listing:  ./mouseex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t M o u s e B u t t o n sf u n c t i o.n }


                Uses     mouse    ;


                 b e g i n
                    I n i t M o u s e;
                    W r i t e l n(' P r e s s r i g h t  mouse     b u t t o n t o   e x i t p r o g r a m') ;
                    While     ( G e t M o u s e B u t t o n<s>M o u s e R i g h t B u t t o)ndo    ;
                    DoneMouse       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                20.4.4         GetMouseDriver

    Synopsis:    Get a copy of the currently active mouse driver.

Declaration:     procedure  GetMouseDriver(var  Driver:  TMouseDriver)

    Visibility:   default

Description:     GetMouseDriver  returns  the  currently  set  mouse  driver.   It  can  be  used  to  retrieve  the
                current mouse driver, and override certain callbacks.

                A more detailed explanation about getting and setting mouse drivers can be found in mouse-
                drv (848  ).

                For an example, see the section on writing a custom mouse driver, mousedrv (848  )

       Errors:   None.

    See also:    SetMouseDriver (855  )
                20.4.5         GetMouseEvent

    Synopsis:    Get next mouse event from the queue.

Declaration:     procedure  GetMouseEvent(var  MouseEvent:  TMouseEvent)

    Visibility:   default

Description:     GetMouseEvent returns the next mouse event (a movement, button press or button release),
                and waits for one if none is available in the queue.

                Some mouse drivers can implement a mouse event queue which can hold multiple events till
                they are fetched.  Others don't, and in that case, a one-event queue is implemented for use
                with PollMouseEvent (855  ).

       Errors:   None.

    See also:    GetMouseButtons (851  ), GetMouseX (853  ), GetMouseY (853  )

                                                                                 852

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
                20.4.6         GetMouseX

    Synopsis:    Query the current horizontal position of the mouse cursor.

Declaration:     function  GetMouseX  :  Word

    Visibility:   default

Description:     GetMouseX returns the current X position of the mouse.  X is measured in characters, starting
                at 0 for the left side of the screen.

       Errors:   None.

    See also:    GetMouseButtons (851  ), GetMouseEvent (852  ), GetMouseY (853  )


                Listing:  ./mouseex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  d e m o n s t r a t et h e  GetMouseX       ,GetMouseY         f u n c t i o n s. }


                Uses     mouse    ;


                Var
                    X ,Y   :  Word    ;


                 b e g i n
                    I n i t M o u s e;
                    W r i t e l n('Move     mouse      c u r s o r t o  s q u a r e 1 0 , 1 0  t o  end   ') ;
                    Repeat
                       X :=  GetMouseX       ;
                       Y :=  GetMouseY       ;
                        W r i t e l n('X ,Y =  (  ' ,X , ' ,' ,Y  ,' ) ' ) ;
                    U n t i l ( X =9)    and    (Y = 9 ) ;
                    DoneMouse       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                20.4.7         GetMouseY

    Synopsis:    Query the current vertical position of the mouse cursor.

Declaration:     function  GetMouseY  :  Word

    Visibility:   default

Description:     GetMouseY returns the current Y position of the mouse.  Y is measured in characters, starting
                at 0 for the top of the screen.

                For an example, see GetMouseX (853  )

       Errors:   None.

    See also:    GetMouseButtons (851  ), GetMouseEvent (852  ), GetMouseX (853  )


                                                                                 853

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
                20.4.8         HideMouse

    Synopsis:    Hide the mouse cursor.

Declaration:     procedure  HideMouse

    Visibility:   default

Description:     HideMouse hides the mouse cursor.  This may or may not be implemented on all systems,
                and depends on the driver.

       Errors:   None.

    See also:    ShowMouse (856  )


                Listing:  ./mouseex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   Program       t o  d e m o n s t r a t et h e  HideMouse         f u n c t i o n. }


                Uses     mouse    ;


                Var
                    E v e n t  :  TMouseEvent        ;
                    V i s i b l e:  B o o l e a n;


                 b e g i n
                    I n i t M o u s e;
                    ShowMouse       ;
                    V i s i b l e:= True   ;
                    W r i t e l n(' P r e s s l e f t  mouse     b u t t o n  t o  h i d e/show    ,  r i g h t b u t t o n  q u i *
 *t s') ;
                    Repeat
                      G e t M o u s e E v e n(tE v e n t) ;
                      With    E v e n t  do
                         I f  ( B u t t o n s=M o u s e L e f t b u t t o)n and
                              ( A c t i o n=MouseActionDown            )  then
                             b e g i n
                             I f  V i s i b l e then
                                HideMouse
                             e l s e
                                ShowMouse       ;
                             V i s i b l e:=Not     V i s i b l e;
                             end  ;
                    U n t i l ( E v e n t. B u t t o n=s M o u s e R i g h t B u t t o)nand
                              ( E v e n t. A c t i o n=MouseActionDown           ) ;
                    DoneMouse       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                20.4.9         InitMouse

    Synopsis:    Initialize the FPC mouse driver.

Declaration:     procedure  InitMouse

    Visibility:   default



                                                                                 854

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
Description:     InitMouse Initializes the mouse driver.  This will allocate any data structures needed for
                the mouse to function.  All mouse functions can be used after a call to InitMouse.

                A call to InitMouse must always be followed by a call to DoneMouse (851  ) at program exit.
                Failing to do so may leave the mouse in an unusable state, or may result in memory leaks.

                For an example, see most other functions.

       Errors:   None.

    See also:    DoneMouse (851  ), DetectMouse (850  )
                20.4.10          PollMouseEvent

    Synopsis:    Query next mouse event.  Do not wait if none available.

Declaration:     function  PollMouseEvent(var  MouseEvent:  TMouseEvent)  :  Boolean

    Visibility:   default

Description:     PollMouseEvent checks whether a mouse event is available, and returns it in MouseEvent
                if one is found.  The function result is True in that case.  If no mouse event is pending, the
                function result is False, and the contents of  MouseEvent is undefined.

                Note that after a call to PollMouseEvent, the event should still be removed from the mouse
                event queue with a call to GetMouseEvent.

       Errors:   None.

    See also:    GetMouseEvent (852  ), PutMouseEvent (855  )
                20.4.11          PutMouseEvent

    Synopsis:    Put a mouse event in the venet queue.

Declaration:     procedure  PutMouseEvent(const  MouseEvent:  TMouseEvent)

    Visibility:   default

Description:     PutMouseEvent  adds  MouseEvent  to  the  input  queue.   The  next  call  to  GetMouseEvent
                (852  ) or PollMouseEvent will then return MouseEvent.

                Please note that depending on the implementation the mouse event queue can hold only one
                value.

       Errors:   None.

    See also:    GetMouseEvent (852  ), PollMouseEvent (855  )
                20.4.12          SetMouseDriver

    Synopsis:    Set a new mouse driver.

Declaration:     procedure  SetMouseDriver(const  Driver:  TMouseDriver)

    Visibility:   default


                                                                                 855

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
Description:     SetMouseDriver  sets  the  mouse  driver  to  Driver.  This  function  should  be  called  before
                InitMouse  (854  )  is  called,  or  after  DoneMouse  is  called.  If  it  is  called  after  the  mouse  has
                been initialized, it does nothing.

                For more information on setting the mouse driver, mousedrv (848  ).

                For an example, see mousedrv (848  )

       Errors:

    See also:    InitMouse (854  ), DoneMouse (851  ), GetMouseDriver (852  )
                20.4.13          SetMouseXY

    Synopsis:    Set the mouse cursor position.

Declaration:     procedure  SetMouseXY(x:  Word;y:  Word)

    Visibility:   default

Description:     SetMouseXY places the mouse cursor on X,Y. X and Y are zero based character coordinates:
                0,0  is  the  top-left  corner  of  the  screen,  and  the  position  is  in  character  cells  (i.e.   not  in
                pixels).

       Errors:   None.

    See also:    GetMouseX (853  ), GetMouseY (853  )


                Listing:  ./mouseex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   Program       t o  d e m o n s t r a t et h e  SetMouseXY         f u n c t i o n.  }


                Uses     mouse    ;


                 b e g i n
                    I n i t M o u s e;
                    W r i t e l n(' C l i c k r i g h t  mouse     b u t t o n t o   q u i t. ') ;
                    SetMouseXY        ( 4 0 , 1 2 ) ;
                    Repeat
                        W r i t e l n(GetMouseX      , ' , ', GetMouseY       ) ;
                        I f  (GetMouseX       >70)     then
                           SetMouseXY       ( 1 0 ,GetMouseY       ) ;
                        I f  (GetMouseY       >20)     then
                           SetMouseXY       ( GetMouseX       , 5 ) ;
                    U n t i l ( G e t M o u s e B u t t o n=sM o u s e R i g h t B u t t)o;n
                    DoneMouse       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                20.4.14          ShowMouse

    Synopsis:    Show the mouse cursor.

Declaration:     procedure  ShowMouse

    Visibility:   default

                                                                                 856

                ___________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________
Description:     ShowMouse shows the mouse cursor if it was previously hidden.  The capability to hide or
                show the mouse cursor depends on the driver.

                For an example, see HideMouse (854  )

       Errors:   None.

    See also:    HideMouse (854  )


                                                                                 857


Chapter   21


Reference   for   unit   'Ob jects'
21.1          Overview


This document 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.
21.2          Constants,  types  and  variables



21.2.1         Constants

coIndexError  =  -1


Collection list error:  Index out of range


coOverflow  =  -2


Collection list error:  Overflow


DefaultTPCompatible  :  Boolean  =  false


DefaultTPCompatible is used to initialize tstream.tpcompatible (??  ).


MaxBytes  =  128  *  1024  *  128


Maximum data size (in bytes)


MaxCollectionSize  =  MaxBytes  div  SizeOf  (  Pointer  )


Maximum collection size (in items)


MaxPtrs  =  MaxBytes  div  SizeOf  (  Pointer  )


Maximum data size (in pointers)



                                                             858

________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___
MaxReadBytes  =  $7fffffff


Maximum data that can be read from a stream (not used)


MaxTPCompatibleCollectionSize  =  65520  div  4


Maximum collection size (in items, same value as in TP)


MaxWords  =  MaxBytes  div  SizeOf  (  Word  )


Maximum data size (in words)


RCollection  :  TStreamRec  =  (ObjType:50;VmtLink:Ofs  (  TypeOf  (  TCollection  )  ^  )  ;Load:@TCollection.Load;Store:@TCollect*
 *ion.Store;Next:nil  )


Default stream record for the TCollection (875  ) object.


RStrCollection  :  TStreamRec  =  (ObjType:69;VmtLink:Ofs  (  TypeOf  (  TStrCollection  )  ^  )  ;Load:@TStrCollection.Load;Store:*
 *@TStrCollection.Store;Next:nil  )


Default stream record for the TStrCollection (914  ) object.


RStringCollection  :  TStreamRec  =  (ObjType:51;VmtLink:Ofs  (  TypeOf  (  TStringCollection  )  ^  )  ;Load:@TStringCollection.Lo*
 *ad;Store:@TStringCollection.Store;Next:nil  )


Default stream record for the TStringCollection (925  ) object.


RStringList  :  TStreamRec  =  (ObjType:52;VmtLink:Ofs  (  TypeOf  (  TStringList  )  ^  )  ;Load:@TStringList.Load;Store:nil;Next:*
 *nil  )


Default stream record for the TStringList (927  ) object.


RStrListMaker  :  TStreamRec  =  (ObjType:52;VmtLink:Ofs  (  TypeOf  (  TStrListMaker  )  ^  )  ;Load:nil;Store:@TStrListMaker.Stor*
 *e;Next:nil  )


Default stream record for the TStrListMaker (928  ) object.


stCreate  =  $3C00


Stream initialization mode:  Create new file


stError  =  -1


Stream error codes:  Access error


stGetError  =  -5


Stream error codes:  Get object error


stInitError  =  -2


Stream error codes:  Initialize error


stOk  =  0


Stream error codes:  No error



                                                                 859

________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___
stOpen  =  $3D02


Stream initialization mode:  Read/write access


stOpenError  =  -8


Stream error codes:  Error opening stream


stOpenRead  =  $3D00


Stream initialization mode:  Read access only


stOpenWrite  =  $3D01


Stream initialization mode:  Write access only


stPutError  =  -6


Stream error codes:  Put object error


stReadError  =  -3


Stream error codes:  Stream read error


StreamError  :  Pointer  =  nil


Pointer to default stream error handler.


stSeekError  =  -7


Stream error codes:  Seek error in stream


stWriteError  =  -4


Stream error codes:  Stream write error


vmtHeaderSize  =  8


Size of the VMT header in an object (not used).
21.2.2         Types

AsciiZ  =  Array[0..255]  of  Char


Filename - null terminated array of characters.


FNameStr  =  String


Filename - shortstring version.
                                                                 860

________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___
LongRec  =  packed  record
   Hi  :  Word;
   Lo  :  Word;
end
Record describing a longint (in Words)


PBufStream  =  ^TBufStream


Pointer to TBufStream (871  ) object.


PByteArray  =  ^TByteArray


Pointer to TByteArray (863  )


PCharSet  =  ^TCharSet


Pointer to TCharSet (863  ).


PCollection  =  ^TCollection


Pointer to TCollection (875  ) object.


PDosStream  =  ^TDosStream


Pointer to TDosStream (890  ) object.


PItemList  =  ^TItemList


Pointer to TItemList (863  ) object.


PMemoryStream  =  ^TMemoryStream


Pointer to TMemoryStream (894  ) object.


PObject  =  ^TObject


Pointer to TObject (896  ) object.


PPoint  =  ^TPoint


Pointer to TPoint (898  ) record.


PPointerArray  =  ^TPointerArray


Pointer to TPointerArray (863  )


PRect  =  ^TRect


Pointer to TRect (898  ) object.



                                                                 861

________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___
PResourceCollection  =  ^TResourceCollection


Pointer to TResourceCollection (904  ) object.


PResourceFile  =  ^TResourceFile


Pointer to TResourceFile (906  ) object.


PSortedCollection  =  ^TSortedCollection


Pointer to TSortedCollection (909  ) object.


PStrCollection  =  ^TStrCollection


Pointer to TStrCollection (914  ) object.


PStream  =  ^TStream


Pointer type to TStream (916  )


PStreamRec  =  ^TStreamRec


Pointer to TStreamRec (863  )


PStrIndex  =  ^TStrIndex


Pointer to TStrIndex (863  ) array.


PString  =  PShortString


Pointer to a shortstring.


PStringCollection  =  ^TStringCollection


Pointer to TStringCollection (925  ) object.


PStringList  =  ^TStringList


Pointer to TStringList (927  ) object.


PStrListMaker  =  ^TStrListMaker


Pointer to TStrListMaker (928  ) object.


PtrRec  =  packed  record
   Ofs  :  Word;
   Seg  :  Word;
end
Record describing a pointer to a memory location.



                                                                 862

________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___
PUnSortedStrCollection  =  ^TUnSortedStrCollection


Pointer to TUnsortedStrCollection (929  ) object.


PWordArray  =  ^TWordArray


Pointer to TWordArray (864  )


Sw_Integer  =  LongInt


Alias for longint


Sw_Word  =  Cardinal


Alias for Cardinal


TByteArray  =  Array[0..MaxBytes-1]  of  Byte


Array with maxmimum allowed number of bytes.


TCharSet  =  Set  of  Char


Generic set of characters type.


TItemList  =  Array[0..MaxCollectionSize-1]  of  Pointer


Pointer array type used in a TCollection (875  )


TPointerArray  =  Array[0..MaxPtrs-1]  of  Pointer


Array with maxmimum allowed number of pointers


TStreamRec  =  packed  record
   ObjType  :  Sw_Word;
   VmtLink  :  pointer;
   Load  :  Pointer;
   Store  :  Pointer;
   Next  :  PStreamRec;
end
TSreamRec is used by the Objects unit streaming mechanism:  when an object is registered,
a TStreamRec record is added to a list of records.  This list is used when objects need to be
streamed from/streamed to a stream.  It contains all the information needed to stream the
object.


TStrIndex  =  Array[0..9999]  of  TStrIndexRec


Pointer array type used in a TStringList (927  )


                                                                 863

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                TStrIndexRec  =  packed  record
                   Key  :  Sw_Word;
                   Count  :  Word;
                   Offset  :  Word;
                end
                Record type used in a TStringList (927  ) to store the strings


                TWordArray  =  Array[0..MaxWords-1]  of  Word


                Array with maxmimum allowed number of words.


                WordRec  =  packed  record
                   Hi  :  Byte;
                   Lo  :  Byte;
                end
                Record describing a Word (in bytes)
                21.2.3         Variables

                invalidhandle  :  THandle


                Value for invalid handle.  Initial value for file stream handles or when the stream is closed.
                21.3          Procedures  and  functions



                21.3.1         Abstract

    Synopsis:    Abstract error handler.

Declaration:     procedure  Abstract

    Visibility:   default

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.
                21.3.2         CallPointerConstructor

    Synopsis:    Call a constructor with a pointer argument.

Declaration:     function  CallPointerConstructor(Ctor:  pointer;Obj:  pointer;VMT:  pointer;
                                                                   Param1:  pointer)  :  pointer

    Visibility:   default
                                                                                 864

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Description:     CallVoidConstructor calls the constructor of an object.  Ctor is the address of the con-
                structor, Obj is a pointer to the instance.  If it is Nil, then a new instance is allocated.  VMT
                is a pointer to the object's VMT. Param1 is passed to the constructor.  The return value is
                a pointer to the instance.

                Note that this can only be used on constructors that require a pointer as the sole argument.
                It can also be used to call a constructor with a single argument by reference.

       Errors:   If the constructor expects other arguments than a pointer, the stack may be corrupted.

    See also:    CallVoidConstructor  (866  ),  CallPointerMethod  (865  ),  CallVoidLocal  (866  ),  CallPointer-
                Local (865  ), CallVoidMethodLocal (867  ), CallPointerMethodLocal (865  )
                21.3.3         CallPointerLocal

    Synopsis:    Call a local nested function with a pointer argument

Declaration:     function  CallPointerLocal(Func:  pointer;Frame:  Pointer;Param1:  pointer)
                                                           :  pointer

    Visibility:   default

Description:     CallPointerLocal calls the local procedure with address Func, where Frame is the frame
                of the wrapping function.  It passes Param1 to the local function.

       Errors:   If the local function expects other parameters than a pointer,  the stack may become cor-
                rupted.

    See also:    CallPointerMethod (865  ), CallVoidMethod (866  ), CallVoidLocal (866  ), CallVoidMethodLo-
                cal (867  ), CallPointerMethodLocal (865  ), CallVoidConstructor (866  ), CallPointerConstruc-
                tor (864  )
                21.3.4         CallPointerMethod

    Synopsis:    Call a method with a single pointer argument

Declaration:     function  CallPointerMethod(Method:  pointer;Obj:  pointer;Param1:  pointer)
                                                             :  pointer

    Visibility:   default

Description:     CallPointerMethod  calls  the  method  with  address  Method  for  instance  Obj.   It  passes
                Param1 to the method as the single argument.  It returns a pointer to the instance.

       Errors:   If the method expects other parameters than a single pointer, the stack may become cor-
                rupted.

    See also:    CallVoidMethod (866  ), CallVoidLocal (866  ), CallPointerLocal (865  ), CallVoidMethodLocal
                (867  ),  CallPointerMethodLocal  (865  ),  CallVoidConstructor  (866  ),  CallPointerConstructor
                (864  )
                21.3.5         CallPointerMethodLocal

    Synopsis:    Call a local procedure of a method with a pointer argument

Declaration:     function  CallPointerMethodLocal(Func:  pointer;Frame:  Pointer;
                                                                   Obj:  pointer;Param1:  pointer)  :  pointer
                                                                                 865

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
    Visibility:  default

Description:     CallPointerMethodLocal calls the local procedure with address Func, where Frame is the
                frame of the wrapping method.  It passes Param1 to the local function.

       Errors:   If the local function expects other parameters than a pointer,  the stack may become cor-
                rupted.

    See also:    CallPointerMethod  (865  ),  CallVoidMethod  (866  ),  CallPointerLocal  (865  ),  CallVoidLocal
                (866  ), CallVoidMethodLocal (867  ), CallVoidConstructor (866  ), CallPointerConstructor (864  )
                21.3.6         CallVoidConstructor

    Synopsis:    Call a constructor with no arguments

Declaration:     function  CallVoidConstructor(Ctor:  pointer;Obj:  pointer;VMT:  pointer)
                                                                :  pointer

    Visibility:   default

Description:     CallVoidConstructor calls the constructor of an object.  Ctor is the address of the con-
                structor, Obj is a pointer to the instance.  If it is Nil, then a new instance is allocated.  VMT
                is a pointer to the object's VMT. The return value is a pointer to the instance.

                Note that this can only be used on constructors that require no arguments.

       Errors:   If the constructor expects arguments, the stack may be corrupted.

    See also:    CallPointerConstructor (864  ), CallPointerMethod (865  ), CallVoidLocal (866  ), CallPointer-
                Local (865  ), CallVoidMethodLocal (867  ), CallPointerMethodLocal (865  )
                21.3.7         CallVoidLocal

    Synopsis:    Call a local nested procedure.

Declaration:     function  CallVoidLocal(Func:  pointer;Frame:  Pointer)  :  pointer

    Visibility:   default

Description:     CallVoidLocal calls the local procedure with address Func,  where Frame is the frame of
                the wrapping function.

       Errors:   If the local function expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod (865  ), CallVoidMethod (866  ), CallPointerLocal (865  ), CallVoidMethod-
                Local  (867  ),  CallPointerMethodLocal  (865  ),  CallVoidConstructor  (866  ),  CallPointerCon-
                structor (864  )
                21.3.8         CallVoidMethod

    Synopsis:    Call an object method

Declaration:     function  CallVoidMethod(Method:  pointer;Obj:  pointer)  :  pointer

    Visibility:   default

Description:     CallVoidMethod calls the method with address Method for instance Obj.  It returns a pointer
                to the instance.
                                                                                 866

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
       Errors:   If the method expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod (865  ), CallVoidLocal (866  ), CallPointerLocal (865  ), CallVoidMethodLo-
                cal (867  ), CallPointerMethodLocal (865  ), CallVoidConstructor (866  ), CallPointerConstruc-
                tor (864  )
                21.3.9         CallVoidMethodLocal

    Synopsis:    Call a local procedure of a method

Declaration:     function  CallVoidMethodLocal(Func:  pointer;Frame:  Pointer;Obj:  pointer)
                                                                :  pointer

    Visibility:   default

Description:     CallVoidMethodLocal  calls  the  local  procedure  with  address  Func,  where  Frame  is  the
                frame of the wrapping method.

       Errors:   If the local function expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod  (865  ),  CallVoidMethod  (866  ),  CallPointerLocal  (865  ),  CallVoidLocal
                (866  ),  CallPointerMethodLocal  (865  ),  CallVoidConstructor  (866  ),  CallPointerConstructor
                (864  )
                21.3.10          DisposeStr

    Synopsis:    Dispose of a shortstring which was allocated on the heap.

Declaration:     procedure  DisposeStr(P:  PString)

    Visibility:   default

Description:     DisposeStr removes a dynamically allocated string from the heap.

                For an example, see NewStr (868  ).

       Errors:   None.

    See also:    NewStr (868  ), SetStr (870  )
                21.3.11          LongDiv

    Synopsis:    Overflow safe divide

Declaration:     function  LongDiv(X:  LongInt;Y:  Integer)  :  Integer

    Visibility:   default

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 (868  )



                                                                                 867

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.3.12          LongMul

    Synopsis:    Overflow safe multiply.

Declaration:     function  LongMul(X:  Integer;Y:  Integer)  :  LongInt

    Visibility:   default

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 (867  )
                21.3.13          NewStr

    Synopsis:    Allocate a copy of a shortstring on the heap.

Declaration:     function  NewStr(const  S:  String)  :  PString

    Visibility:   default

Description:     NewStr makes a copy of the string S on the heap, and returns a pointer to this copy.  If the
                string is empty then Nil is returned.

                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 (867  ), SetStr (870  )


                Listing:  ./objectex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 4 0 ;


                {   Program       t o  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';
                    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 gi s  wrong      ! ! ') ;
                    D i s p o s e S t(rP ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.3.14          RegisterObjects

    Synopsis:    Register standard objects.

Declaration:     procedure  RegisterObjects

    Visibility:   default



                                                                                 868

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Description:     RegisterObjects registers the following objects for streaming:


                     1.TCollection, see TCollection (875  ).

                     2.TStringCollection, see TStringCollection (925  ).

                     3.TStrCollection, see TStrCollection (914  ).


       Errors:   None.

    See also:    RegisterType (869  )
                21.3.15          RegisterType

    Synopsis:    Register new object for streaming.

Declaration:     procedure  RegisterType(var  S:  TStreamRec)

    Visibility:   default

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.

                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.

                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.


                The VMT of the object can be retrieved with the following expression:


                VmtLink:  Ofs(TypeOf(MyType)^);


       Errors:   In case of error (if a object with the same ObjType) is already registered), run-time error
                212 occurs.


                Listing:  ./objectex/myobject.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 U n i t MyObject      ;



                 I n t e r f a c e


                Uses     O b j e c t s;


                Type
                         PMyObject        =  ^  TMyObject       ;
                         TMyObject        =   O b j e c t(T O b j e c t)
                             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    S t r e a m :   TStream     ) ;
                             D e s t r u c t o rDone   ;
                             P r o c e d u r eS t o r e ( Var    S t r e a m  :  TStream     ) ;



                                                                                 869

            ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_____________________*
 *_______________
                         F u n c t i o n  G e t F i e l d :  L o n g i n t;
                         P r o c e d u r eS 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    S t r e a m  :  TStream     ) ;


             b e g i n
                S t r e a m.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   ;


             P r o c e d u r eTMyObject       . 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   ;


             P r o c e d u r eTMyObject       .S t o r e  (Var     S t r e a m :  TStream      ) ;


             b e g i n
                S t r e a m.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___.________________________________________________________________________________________________________________*
 *_______

            21.3.16          SetStr

Synopsis:    Allocate a copy of a shortstring on the heap.



                                                                             870

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Declaration:     procedure  SetStr(var  p:  PString;const  s:  String)

    Visibility:  default

Description:     SetStr makes a copy of the string S on the heap and returns the pointer to this copy in P.
                If  P pointed to another string (i.e.  was not Nil, the memory is released first.  Contrary to
                NewStr (868  ), if the string is empty then a pointer to an empty string is returned.

                The allocated memory is not based on the declared size of the string passed to NewStr, but
                is based on the actual length of the string.

       Errors:   If not enough memory is available, an 'out of memory' error will occur.

    See also:    DisposeStr (867  ), NewStr (868  )
                21.4          TBufStream



                21.4.1         Description

                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.
                21.4.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  872       Close            Flush data and Close the file.
                  872       Done             Close the file and cleans up the instance.
                  872       Flush            FLush data from buffer, and write it to stream.
                  871       Init             Initialize an instance of  TBufStream and open the file.
                  874       Open             Open the file if it is closed.
                  874       Read             Read data from the file to a buffer in memory.
                  873       Seek             Set current position in file.
                  873       Truncate         Flush buffer, and truncate the file at current position.
                __874_______Write____________Write_data_to_the_file_from_a_buffer_in_memory._______________________________________*
 *___________
                21.4.3         TBufStream.Init

    Synopsis:    Initialize an instance of  TBufStream and open the file.

Declaration:     constructor  Init(FileName:  FNameStr;Mode:  Word;Size:  Word)

    Visibility:   default

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.



                                                                                 871

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                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.

                For an example see TBufStream.Flush (872  ).

       Errors:   On error, Status is set to stInitError, and ErrorInfo is set to the dos error code.

    See also:    TDosStream.Init (890  ), TBufStream.Done (872  )
                21.4.4         TBufStream.Done

    Synopsis:    Close the file and cleans up the instance.

Declaration:     destructor  Done;    Virtual

    Visibility:   default

Description:     Done flushes and closes the file if it was open and cleans up the instance of  TBufStream.

                For an example see TBufStream.Flush (872  ).

       Errors:   None.

    See also:    TDosStream.Done (890  ), TBufStream.Init (871  ), TBufStream.Close (872  )
                21.4.5         TBufStream.Close

    Synopsis:    Flush data and Close the file.

Declaration:     procedure  Close;    Virtual

    Visibility:   default

Description:     Close flushes and closes the file if it was open, and sets Handle to -1.  Contrary to Done
                (872  ) it does not clean up the instance of  TBufStream

                For an example see TBufStream.Flush (872  ).

       Errors:   None.

    See also:    TStream.Close (920  ), TBufStream.Init (871  ), TBufStream.Done (872  )
                21.4.6         TBufStream.Flush

    Synopsis:    FLush data from buffer, and write it to stream.

Declaration:     procedure  Flush;    Virtual

    Visibility:   default

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 (874  ) for more info on the
                errors.



                                                                                 872

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
    See also:    TStream.Close (920  ), TBufStream.Init (871  ), TBufStream.Done (872  )


                Listing:  ./objectex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 5 ;


                {   Program       t o  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        ;  {   O n l y  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  ,' "  t o   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     ( s t O p e n R e a)d;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t(rP ) ;
                    W r i t e l n ( 'Read     " ' ,L , ' "  f r o m  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___.____________________________________________________________________________________________________________*
 *___________

                21.4.7         TBufStream.Truncate

    Synopsis:    Flush buffer, and truncate the file at current position.

Declaration:     procedure  Truncate;    Virtual

    Visibility:   default

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.

                For an example, see TDosStream.Truncate (891  ).

       Errors:   Errors can be those of Flush (872  ) or TDosStream.Truncate (891  ).

    See also:    TStream.Truncate (921  ), TDosStream.Truncate (891  ), TStream.GetSize (919  )
                21.4.8         TBufStream.Seek

    Synopsis:    Set current position in file.

Declaration:     procedure  Seek(Pos:  LongInt);    Virtual



                                                                                 873

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
    Visibility:  default

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.

                For an example, see TStream.Seek (922  );

       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 (922  ), TStream.GetPos (918  )
                21.4.9         TBufStream.Open

    Synopsis:    Open the file if it is closed.

Declaration:     procedure  Open(OpenMode:  Word);    Virtual

    Visibility:   default

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 (872  ) call.

                For an example, see TDosStream.Open (893  ).

       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 (920  ), TBufStream.Close (872  )
                21.4.10          TBufStream.Read

    Synopsis:    Read data from the file to a buffer in memory.

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

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.

                For an example, see TStream.Read (923  ).

       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 (923  ), TBufStream.Write (874  )
                21.4.11          TBufStream.Write

    Synopsis:    Write data to the file from a buffer in memory.

Declaration:     procedure  Write(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

                                                                                 874

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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.

                For an example, see TStream.Read (923  ).

       Errors:   In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                error.

    See also:    TStream.Write (924  ), TBufStream.Read (874  )
                21.5          TCollection



                21.5.1         Description

                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.
                21.5.2         Method  overview

                __Page______Property__________Description__________________________________________________________________________*
 *___________
                  877       At                Return the item at a certain index.
                  886       AtDelete          Delete item at certain position.
                  885       AtFree            Free an item at the indicates position, calling it's destructor.
                  888       AtInsert          Insert an element at a certain position in the collection.
                  888       AtPut             Set collection item, overwriting an existing value.
                  884       Delete            Delete an item from the collection, but does not destroy it.
                  882       DeleteAll         Delete all elements from the collection.  Objects are not destroyed.
                  877       Done              Clean up collection, release all memory.
                  888       Error             Set error code.
                  880       FirstThat         Return first item which matches a test.
                  886       ForEach           Execute procedure for each item in the list.
                  883       Free              Free item from collection, calling it's destructor.
                  881       FreeAll           Release all objects from the collection.
                  885       FreeItem          Destroy a non-nil item.
                  879       GetItem           Read one item off the stream.
                  878       IndexOf           Find the position of a certain item.
                  875       Init              Instantiate a new collection.
                  884       Insert            Insert a new item in the collection at the end.
                  879       LastThat          Return last item which matches a test.
                  876       Load              Initialize a new collection and load collection from a stream.
                  881       Pack              Remove all >Nil pointers from the collection.
                  889       PutItem           Put one item on the stream
                  887       SetLimit          Set maximum number of elements in the collection.
                __889_______Store_____________Write_collection_to_a_stream.________________________________________________________*
 *___________
                21.5.3         TCollection.Init

    Synopsis:    Instantiate a new collection.



                                                                                 875

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Declaration:     constructor  Init(ALimit:  Sw_Integer;ADelta:  Sw_Integer)

    Visibility:  default

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.

                For an example, see TCollection.ForEach (886  ).

       Errors:   None.

    See also:    TCollection.Load (876  ), TCollection.Done (877  )
                21.5.4         TCollection.Load

    Synopsis:    Initialize a new collection and load collection from a stream.

Declaration:     constructor  Load(var  S:  TStream)

    Visibility:   default

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 (879  ).

    See also:    TCollection.Init (875  ), TCollection.GetItem (879  ), TCollection.Done (877  )


                Listing:  ./objectex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 2 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nLoad     method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    C := New  ( P C o l l e c t i o n,I n i t( 1 0 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 f r o m  s t r e a m.' ) ;
                    D i s p o s e(S ,Done    ) ;



                                                                                 876

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.5         TCollection.Done

    Synopsis:    Clean up collection, release all memory.

Declaration:     destructor  Done;    Virtual

    Visibility:   default

Description:     Done  frees  all  objects  in  the  collection,  and  then  releases  all  memory  occupied  by  the  in-
                stance.

                For an example, see TCollection.ForEach (886  ).

       Errors:   None.

    See also:    TCollection.Init (875  ), TCollection.FreeAll (881  )
                21.5.6         TCollection.At

    Synopsis:    Return the item at a certain index.

Declaration:     function  At(Index:  Sw_Integer)  :  Pointer

    Visibility:   default

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, seepl{Error}{TCollection.Error}
                is called with coIndexError and Index as arguments, resulting in a run-time error.

    See also:    TCollection.Insert (884  )


                Listing:  ./objectex/ex23.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 3 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nAt   method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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 n,I n i t( 1 0 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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  t o  C ^ .Count    -1   do
                        b e g i n
                       M := C  ^ .At ( I ) ;



                                                                                 877

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                        W r i t e l n(  'O b j e c t ' , i ,'   h a s  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___.____________________________________________________________________________________________________________*
 *___________

                21.5.7         TCollection.IndexOf

    Synopsis:    Find the position of a certain item.

Declaration:     function  IndexOf(Item:  Pointer)  :  Sw_Integer;    Virtual

    Visibility:   default

Description:     IndexOf returns the index of  Item in the collection.  If  Item isn't present in the collection,
                -1 is returned.

       Errors:   If the item is not present, -1 is returned.

    See also:    TCollection.At (877  ), TCollection.GetItem (879  ), TCollection.Insert (884  )


                Listing:  ./objectex/ex24.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 4 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nI n d e x O f method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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 n,I n i t( 1 0 0 , 1 0 ) ) ;
                    Keep   :=  N i l;
                    For    I : = 1  t o  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 r u n  a g a i n.  No    o b j e c t s e l e c t e d') ;
                       H a l t ( 1 ) ;
                       end   ;
                    W r i t e l n ( ' S e l e c t e do b j e c t h a s   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 h a s  i n d e x :   ' ,C ^ . I n d e x O f(Keep   ) ) ;
                    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;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                 878

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.5.8         TCollection.GetItem

    Synopsis:    Read one item off the stream.

Declaration:     function  GetItem(var  S:  TStream)  :  Pointer;    Virtual

    Visibility:   default

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 (917  ).

    See also:    TStream.Get (917  ), TCollection.Store (889  )
                21.5.9         TCollection.LastThat

    Synopsis:    Return last item which matches a test.

Declaration:     function  LastThat(Test:  Pointer)  :  Pointer

    Visibility:   default

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:    TCollection.FirstThat (880  )


                Listing:  ./objectex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 1 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nF o r e a c h method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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 nC 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<d56   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 n,I n i t( 1 0 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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   ;



                                                                                 879

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    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  w h i c h  F i e l d<56     h a s  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) ) ;
                    C ^ .F r e e A l l;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.10          TCollection.FirstThat

    Synopsis:    Return first item which matches a test.

Declaration:     function  FirstThat(Test:  Pointer)  :  Pointer

    Visibility:   default

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:    TCollection.LastThat (879  )


                Listing:__./objectex/ex26.pp_______________________________________________________________________________________*
 *___________

                Program       e x 2 1 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nF i r s t T h a tmethod      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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 nC 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>d56   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 n,I n i t( 1 0 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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  w h i c h F i e l d>56      h a s  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                 880

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.5.11          TCollection.Pack

    Synopsis:    Remove all >Nil pointers from the collection.

Declaration:     procedure  Pack

    Visibility:   default

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.

       Errors:   None.

    See also:    TCollection.SetLimit (887  )


                Listing:  ./objectex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 1 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nF i r s t T h a tmethod      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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 nC 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>d56   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 n,I n i t( 1 0 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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  w h i c h F i e l d>56      h a s  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___.____________________________________________________________________________________________________________*
 *___________

                21.5.12          TCollection.FreeAll

    Synopsis:    Release all objects from the collection.

Declaration:     procedure  FreeAll

    Visibility:   default



                                                                                 881

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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:    TCollection.DeleteAll (882  ), TCollection.FreeItem (885  )


                Listing:  ./objectex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 8 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nF r e e A l l method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    Randomize       ;
                    C := New  ( P C o l l e c t i o n,I n i t( 1 2 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 0  I t e m s. ') ;
                    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.' ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.13          TCollection.DeleteAll

    Synopsis:    Delete all elements from the collection.  Objects are not destroyed.

Declaration:     procedure  DeleteAll

    Visibility:   default

Description:     DeleteAll deletes all elements from the collection.  It just sets the Count variable to zero.
                Contrary to FreeAll (881  ), DeletAll doesn't call the destructor of the objects.

       Errors:   None.

    See also:    TCollection.FreeAll (881  ), TCollection.Delete (884  )


                Listing:  ./objectex/ex29.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 9 ;


                {
                  Program       t o   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 e A l lmethod
                  Compare       w i t h  e x a m p l e 2 8 ,  w h e r e F r e e A l l  i s  u s e d.
                }

                                                                                 882

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    Randomize       ;
                    C := New  ( P C o l l e c t i o n,I n i t( 1 2 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 0  I t e m s. ') ;
                    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.') ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.14          TCollection.Free

    Synopsis:    Free item from collection, calling it's destructor.

Declaration:     procedure  Free(Item:  Pointer)

    Visibility:   default

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:    TCollection.FreeItem (885  )


                Listing:  ./objectex/ex30.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 0 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nF r e e  method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    Randomize       ;
                    C := New  ( P C o l l e c t i o n,I n i t( 1 2 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 0  I t e m s. ') ;
                    With    C  ^  do



                                                                                 883

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                       While      Count    >0   do   F r e 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.' ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.15          TCollection.Insert

    Synopsis:    Insert a new item in the collection at the end.

Declaration:     procedure  Insert(Item:  Pointer);    Virtual

    Visibility:   default

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:    TCollection.AtInsert (888  ), TCollection.AtPut (888  )
                21.5.16          TCollection.Delete

    Synopsis:    Delete an item from the collection, but does not destroy it.

Declaration:     procedure  Delete(Item:  Pointer)

    Visibility:   default

Description:     Delete deletes Item from the collection.  It doesn't call the item's destructor, though.  For
                this the Free (883  ) call is provided.

       Errors:   If the Item is not in the collection, Error will be called with coIndexError.

    See also:    TCollection.AtDelete (886  ), TCollection.Free (883  )


                Listing:  ./objectex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 1 ;


                {   Program       t o  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 method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    Randomize       ;
                    C := New  ( P C o l l e c t i o n,I n i t( 1 2 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 0  I t e m s. ') ;
                    With    C  ^  do



                                                                                 884

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                       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') ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.17          TCollection.AtFree

    Synopsis:    Free an item at the indicates position, calling it's destructor.

Declaration:     procedure  AtFree(Index:  Sw_Integer)

    Visibility:   default

Description:     AtFree deletes the item at position Index in the collection, and calls the item's destructor
                if it is not Nil.

       Errors:   If  Index isn't valid then Error (888  ) is called with CoIndexError.

    See also:    TCollection.Free (883  ), TCollection.AtDelete (886  )


                Listing:  ./objectex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 2 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nA t F r e e method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    Randomize       ;
                    C := New  ( P C o l l e c t i o n,I n i t( 1 2 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 0  I t e m s' ) ;
                    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.' ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.18          TCollection.FreeItem

    Synopsis:    Destroy a non-nil item.

Declaration:     procedure  FreeItem(Item:  Pointer);    Virtual

    Visibility:   default

                                                                                 885

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Description:     FreeItem calls the destructor of  Item if it is not nil.

 Remark:        This function is used internally by the TCollection object, and should not be called directly.

       Errors:   None.

    See also:    TCollection.Free (883  ), TCollection.AtFree (885  )
                21.5.19          TCollection.AtDelete

    Synopsis:    Delete item at certain position.

Declaration:     procedure  AtDelete(Index:  Sw_Integer)

    Visibility:   default

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 (888  ) is called with CoIndexError.

    See also:    TCollection.Delete (884  )


                Listing:  ./objectex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 3 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nA t D e l e t e method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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
                    Randomize       ;
                    C := New  ( P C o l l e c t i o n,I n i t( 1 2 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 0  I t e m s. ') ;
                    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.' ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.5.20          TCollection.ForEach

    Synopsis:    Execute procedure for each item in the list.

Declaration:     procedure  ForEach(Action:  Pointer)

    Visibility:   default



                                                                                 886

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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:    TCollection.FirstThat (880  ), TCollection.LastThat (879  )


                Listing:  ./objectex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 1 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nF o r e a c h method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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;


                 P r o c e d u r eP 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
                    C := New  ( P C o l l e c t i o n,I n i t( 1 0 0 , 1 0 ) ) ;
                    For    I : = 1  t o  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 ^ .F o r E a c h(@ 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___.____________________________________________________________________________________________________________*
 *___________

                21.5.21          TCollection.SetLimit

    Synopsis:    Set maximum number of elements in the collection.

Declaration:     procedure  SetLimit(ALimit:  Sw_Integer);    Virtual

    Visibility:   default

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

                For an example, see Pack (881  ).

       Errors:   None.

    See also:    TCollection.Init (875  )


                                                                                 887

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.5.22          TCollection.Error

    Synopsis:    Set error code.

Declaration:     procedure  Error(Code:  Integer;Info:  Integer);    Virtual

    Visibility:   default

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 (864  )
                21.5.23          TCollection.AtPut

    Synopsis:    Set collection item, overwriting an existing value.

Declaration:     procedure  AtPut(Index:  Sw_Integer;Item:  Pointer)

    Visibility:   default

Description:     AtPut sets the element at position Index in the collection to Item.  Any previous value is
                overwritten.

                For an example, see Pack (881  ).

       Errors:   If  Index isn't valid then Error (888  ) is called with CoIndexError.
                21.5.24          TCollection.AtInsert

    Synopsis:    Insert an element at a certain position in the collection.

Declaration:     procedure  AtInsert(Index:  Sw_Integer;Item:  Pointer)

    Visibility:   default

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 (888  ) is called with CoIndexError.  If the collection fails to
                expand, then coOverFlow is passd to Error.

    See also:    TCollection.Insert (884  )


                Listing:  ./objectex/ex34.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 4 ;


                {   Program       t o  d e m o n s t r a t et h e  T C o l l e c t i o.nA t I n s e r t method      }


                Uses     O b j e c t s,MyObject      ;  {   F o r  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;
                                                                                 888

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                 P r o c e d u r eP 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 n,I n i t( 1 2 0 , 1 0 ) ) ;
                    W r i t e l n ( ' I n s e r t i n g1 0 0  r e c o r d s a t  random      p l a c e s. ') ;
                    For    I : = 1  t o  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(tRandom     (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___.____________________________________________________________________________________________________________*
 *___________

                21.5.25          TCollection.Store

    Synopsis:    Write collection to a stream.

Declaration:     procedure  Store(var  S:  TStream)

    Visibility:   default

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
                (876  ).

                For an example, see TCollection.Load (876  ).

       Errors:   Errors returned are those by TStream.Put (922  ).

    See also:    TCollection.Load (876  ), TCollection.PutItem (889  )
                21.5.26          TCollection.PutItem

    Synopsis:    Put one item on the stream

Declaration:     procedure  PutItem(var  S:  TStream;Item:  Pointer);    Virtual

    Visibility:   default

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 (922  ).

    See also:    TCollection.Store (889  ), TCollection.GetItem (879  )



                                                                                 889

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.6          TDosStream



                21.6.1         Description

                TDosStream is a stream that stores it's contents in a file.  it overrides a couple of methods of
                TStream (916  ) for this.

                In addition to the fields inherited from TStream (see TStream (916  )), 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 TBufStream (871  ).
                21.6.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  891       Close            Close the file.
                  890       Done             Closes the file and cleans up the instance.
                  890       Init             Instantiate a new instance of TDosStream.
                  893       Open             Open the file stream
                  893       Read             Read data from the stream to a buffer.
                  892       Seek             Set file position.
                  891       Truncate         Truncate the file on the current position.
                __894_______Write____________Write_data_from_a_buffer_to_the_stream._______________________________________________*
 *___________
                21.6.3         TDosStream.Init

    Synopsis:    Instantiate a new instance of TDosStream.

Declaration:     constructor  Init(FileName:  FNameStr;Mode:  Word)

    Visibility:   default

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.


                For an example, see TDosStream.Truncate (891  ).

       Errors:   On error, Status (??  ) is set to stInitError, and ErrorInfo is set to the dos error code.

    See also:    TDosStream.Done (890  )
                21.6.4         TDosStream.Done

    Synopsis:    Closes the file and cleans up the instance.

Declaration:     destructor  Done;    Virtual

    Visibility:   default



                                                                                 890

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Description:     Done closes the file if it was open and cleans up the instance of  TDosStream.

                for an example, see e.g.  TDosStream.Truncate (891  ).

       Errors:   None.

    See also:    TDosStream.Init (890  ), TDosStream.Close (891  )
                21.6.5         TDosStream.Close

    Synopsis:    Close the file.

Declaration:     procedure  Close;    Virtual

    Visibility:   default

Description:     Close closes the file if it was open, and sets Handle to -1.  Contrary to Done (890  ) it does
                not clean up the instance of  TDosStream

                For an example, see TDosStream.Open (893  ).

       Errors:   None.

    See also:    TStream.Close (920  ), TDosStream.Init (890  ), TDosStream.Done (890  )
                21.6.6         TDosStream.Truncate

    Synopsis:    Truncate the file on the current position.

Declaration:     procedure  Truncate;    Virtual

    Visibility:   default

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 (921  ), TStream.GetSize (919  )


                Listing:  ./objectex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 6 ;


                {   Program       t o  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        ;  {   O n l y  one    w i t h T r u n c a t e 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  ( 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  ,' "  t o   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  ) ;



                                                                                 891

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    {   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     ( s t O p e n) ;
                    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(rP ) ;
                    W r i t e l n ( 'Read     " ' ,L , ' "  f r o m  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___.____________________________________________________________________________________________________________*
 *___________

                21.6.7         TDosStream.Seek

    Synopsis:    Set file position.

Declaration:     procedure  Seek(Pos:  LongInt);    Virtual

    Visibility:   default

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 (922  ), TStream.GetPos (918  )


                Listing:  ./objectex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 7 ;


                {   Program       t o  d e m o n s t r a t et h e  TStream     . S e e k  method      }


                Uses     O b j e c t s;


                Var    L   :   S t r i n g;
                       M a r k e r  :  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  ,' "  t o   s t r e a m.' ) ;
                    S ^ .W r i t e S t r(@L  ) ;
                    M a r k e r:= S ^ .G e t P o s;
                    W r i t e l n ( 'S e t  m a r k e r  a t  ' ,M a r k e r) ;
                    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  ,' "  t o   s t r e a m.' ) ;
                    S ^ .W r i t e S t r(@L  ) ;
                    S ^ .C l o s e;
                    S ^ .Open     ( s t O p e n R e a)d;
                    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 gt o   m a r k e r') ;



                                                                                 892

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    S ^ .Seek   ( M a r k e r) ;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t(rP ) ;
                    W r i t e l n ( 'Read     " ' ,L , ' "  f r o m  s t r e a m.' ) ;
                    S ^ .C l o s e;
                    D i s p o s e (S  ,Done   ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.6.8         TDosStream.Open

    Synopsis:    Open the file stream

Declaration:     procedure  Open(OpenMode:  Word);    Virtual

    Visibility:   default

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 (891  ) 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 (920  ), TDosStream.Close (891  )


                Listing:  ./objectex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 4 ;


                {   Program       t o  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        ;  {   O n l y  one    w i t h C l o s e  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';
                    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  ,' "  t o   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     ( s t O p e n R e a)d;
                    P := S ^ . R e a d S t r;
                    L := P ^ ;
                    D i s p o s e S t(rP ) ;
                    W r i t e l n ( 'Read     " ' ,L , ' "  f r o m  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___.____________________________________________________________________________________________________________*
 *___________

                21.6.9         TDosStream.Read

    Synopsis:    Read data from the stream to a buffer.



                                                                                 893

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual

    Visibility:  default

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.

                For an example, see TStream.Read (923  ).

       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 (923  ), TDosStream.Write (894  )
                21.6.10          TDosStream.Write

    Synopsis:    Write data from a buffer to the stream.

Declaration:     procedure  Write(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

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.

                For an example, see TStream.Read (923  ).

       Errors:   In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                error.

    See also:    TStream.Write (924  ), TDosStream.Read (893  )
                21.7          TMemoryStream



                21.7.1         Description

                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.
                21.7.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  895       Done             Clean up memory and destroy the object instance.
                  894       Init             Initialize memory stream, reserves memory for stream data.
                  896       Read             Read data from the stream to a location in memory.
                  895       Truncate         Set the stream size to the current position.
                __896_______Write____________Write_data_to_the_stream._____________________________________________________________*
 *___________
                21.7.3         TMemoryStream.Init

    Synopsis:    Initialize memory stream, reserves memory for stream data.

Declaration:     constructor  Init(ALimit:  LongInt;ABlockSize:  Word)

    Visibility:   default
                                                                                 894

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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.

                For an example, see e.g TStream.CopyFrom (924  ).

       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:    TMemoryStream.Done (895  )
                21.7.4         TMemoryStream.Done

    Synopsis:    Clean up memory and destroy the object instance.

Declaration:     destructor  Done;    Virtual

    Visibility:   default

Description:     Done releases the memory blocks used by the stream, and then cleans up the memory used
                by the stream object itself.

                For an example, see e.g TStream.CopyFrom (924  ).

       Errors:   None.

    See also:    TMemoryStream.Init (894  )
                21.7.5         TMemoryStream.Truncate

    Synopsis:    Set the stream size to the current position.

Declaration:     procedure  Truncate;    Virtual

    Visibility:   default

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 (921  )


                Listing:  ./objectex/ex20.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 0 ;


                {   Program       t o  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  :   L o n g i n t;

                                                                                 895

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                 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  ( PMemoryStream          , I n i t( 1 0 0 0 , 1 0 0 ) ) ;
                    W r i t e l n ( ' W r i t i n g1 0 0  t i m e s "  ' ,L , '"   t o  s t r e a m. ') ;
                    For    I : = 1  t o  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.') ;
                    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 .' ) ;
                    D i s p o s e (S  ,Done   ) ;
                    W r i t e l n ( ' F i n i s h e d.') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.7.6         TMemoryStream.Read

    Synopsis:    Read data from the stream to a location in memory.

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

Description:     Read reads Count bytes from the stream to Buf.  It updates the position of the stream.

                For an example, see TStream.Read (923  ).

       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 (923  ), TMemoryStream.Write (896  )
                21.7.7         TMemoryStream.Write

    Synopsis:    Write data to the stream.

Declaration:     procedure  Write(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

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 (894  )) as needed.

                For an example, see TStream.Read (923  ).

       Errors:   If the stream cannot allocate more memory, then the status is set to stWriteError

    See also:    TStream.Write (924  ), TMemoryStream.Read (896  )
                21.8          TOb ject



                21.8.1         Description

                This type serves as the basic object for all other objects in the Objects unit.
                                                                                 896

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.8.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  898       Done             Destroy an object.
                  897       Free             Destroy an object and release all memory.
                  897       Init             Construct (initialize) a new object
                __898_______Is_Object________Check_whether_a_pointer_points_to_an_object.__________________________________________*
 *___________
                21.8.3         TObject.Init

    Synopsis:    Construct (initialize) a new object

Declaration:     constructor  Init

    Visibility:   default

Description:     Instantiates a new object of type TObject.  It fills the instance up with Zero bytes.

                For an example, see Free (897  )

       Errors:   None.

    See also:    TObject.Free (897  ), TObject.Done (898  )
                21.8.4         TObject.Free

    Synopsis:    Destroy an object and release all memory.

Declaration:     procedure  Free

    Visibility:   default

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:    TObject.Init (897  ), TObject.Done (898  )


                Listing:  ./objectex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x 7 ;


                {   Program       t o  d e m o n s t r a t et h e  T O b j e c t.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
                    //   A l l o c a t e memory      f o r  o b j e c t.
                    O := New  ( P O b j e c t,I n i t) ;
                    //   F r e e  memory      o f   o b j e c t.
                    O ^ .f r e e;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                 897

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.8.5         TObject.Is__Object

    Synopsis:    Check whether a pointer points to an object.

Declaration:     function  Is_Object(P:  Pointer)  :  Boolean

    Visibility:   default

Description:     Is_Object returns True if the pointer P points to an instance of a TObject descendent, it
                returns false otherwise.
                21.8.6         TObject.Done

    Synopsis:    Destroy an object.

Declaration:     destructor  Done;    Virtual

    Visibility:   default

Description:     Done,  the  destructor  of  TObject  does  nothing.   It  is  mainly  intended  to  be  used  in  the
                TObject.Free (897  ) method.

                The destructore Done does not free the memory occupied by the object.

       Errors:   None.

    See also:    TObject.Free (897  ), TObject.Init (897  )


                Listing:  ./objectex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x 8 ;


                {   Program       t o  d e m o n s t r a t et h e  T O b j e c t.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
                    //   A l l o c a t e memory      f o r  o b j e c t.
                    O := New  ( P O b j e c t,I n i t) ;
                    O ^ .Done   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.9          TPoint



                21.9.1         Description

                Record describing a point in a 2 dimensional plane.
                21.10            TRect



                21.10.1          Description

                Describes a rectangular region in a plane.

                                                                                 898

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.10.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  904       Assign          Set rectangle corners.
                  900       Contains        Determine if a point is inside the rectangle
                  900       Copy            Copy cornerpoints from another rectangle.
                  899       Empty           Is the surface of the rectangle zero
                  900       Equals          Do the corners of the rectangles match
                  903       Grow            Expand rectangle with certain size.
                  902       Intersect       Reduce rectangle to intersection with another rectangle
                  902       Move            Move rectangle along a vector.
                __901_______Union___________Enlarges_rectangle_to_encompas_another_rectangle.______________________________________*
 *___________
                21.10.3          TRect.Empty

    Synopsis:    Is the surface of the rectangle zero

Declaration:     function  Empty  :  Boolean

    Visibility:   default

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 (900  ), TRect.Contains (900  )


                Listing:  ./objectex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 ;


                {   Program       t o  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   :  T P o i n t;


                 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 tB   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



                                                                                 899

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                       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 s(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.10.4          TRect.Equals

    Synopsis:    Do the corners of the rectangles match

Declaration:     function  Equals(R:  TRect)  :  Boolean

    Visibility:   default

Description:     Equals returns True if the rectangle has the same corner points A,B as the rectangle R, and
                False otherwise.

                For an example, see TRect.Empty (899  )

       Errors:   None.

    See also:    TRect.Empty (899  ), TRect.Contains (900  )
                21.10.5          TRect.Contains

    Synopsis:    Determine if a point is inside the rectangle

Declaration:     function  Contains(P:  TPoint)  :  Boolean

    Visibility:   default

Description:     Contains returns True if the point P is contained in the rectangle (including borders), False
                otherwise.

       Errors:   None.

    See also:    TRect.Intersect (902  ), TRect.Equals (900  )
                21.10.6          TRect.Copy

    Synopsis:    Copy cornerpoints from another rectangle.

Declaration:     procedure  Copy(R:  TRect)

    Visibility:   default

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.
                                                                                 900

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
       Errors:   None.

    See also:    TRect.Assign (904  )


                Listing:  ./objectex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 2 ;


                {   Program       t o  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  n o t  e q u a l CRect      ! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.10.7          TRect.Union

    Synopsis:    Enlarges rectangle to encompas another rectangle.

Declaration:     procedure  Union(R:  TRect)

    Visibility:   default

Description:     Union enlarges the current rectangle so that it becomes the union of the current rectangle
                with the rectangle R.

       Errors:   None.

    See also:    TRect.Intersect (902  )


                Listing:  ./objectex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 ;


                {   Program       t o  d e m o n s t r a t eTRect    . U n i o n }


                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    .U n i o n( BRect    ) ;
                    I f  ARect    . E q u a l s(CRect    )  Then



                                                                                 901

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                        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  n o t  e q u a l CRect      ! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.10.8          TRect.Intersect

    Synopsis:    Reduce rectangle to intersection with another rectangle

Declaration:     procedure  Intersect(R:  TRect)

    Visibility:   default

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:    TRect.Union (901  )


                Listing:  ./objectex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 4 ;


                {   Program       t o  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
                        W r i t e l n(  'ARect     d o e s  n o t  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___.____________________________________________________________________________________________________________*
 *___________

                21.10.9          TRect.Move

    Synopsis:    Move rectangle along a vector.

Declaration:     procedure  Move(ADX:  Sw_Integer;ADY:  Sw_Integer)

    Visibility:   default

                                                                                 902

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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:    TRect.Grow (903  )


                Listing:  ./objectex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 5 ;


                {   Program       t o  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   w h e r e 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  n o t  e q u a l BRect      ! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.10.10           TRect.Grow

    Synopsis:    Expand rectangle with certain size.

Declaration:     procedure  Grow(ADX:  Sw_Integer;ADY:  Sw_Integer)

    Visibility:   default

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:    TRect.Move (902  )


                Listing:  ./objectex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 6 ;


                {   Program       t o  d e m o n s t r a t eTRect    .Grow     }


                Uses     o b j e c t s;



                                                                                 903

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                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   w h e r e 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  n o t  e q u a l BRect      ! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.10.11           TRect.Assign

    Synopsis:    Set rectangle corners.

Declaration:     procedure  Assign(XA:  Sw_Integer;YA:  Sw_Integer;XB:  Sw_Integer;
                                           YB:  Sw_Integer)

    Visibility:   default

Description:     Assign sets the corner points of the rectangle to (XA,YA) and (Xb,Yb).

                For an example, see TRect.Copy (900  ).

       Errors:   None.

    See also:    TRect.Copy (900  )
                21.11            TResourceCollection



                21.11.1          Description

                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:          Remark  that  the  TResourceCollection  manages  the  names  of  the  resources  and  their
                assiciated positions and sizes, it doesn't manage the resources themselves.
                                                                                 904

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.11.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  905       FreeItem        Release memory occupied by item.
                  905       GetItem         Read an item from the stream.
                  905       KeyOf           Return the key of an item in the collection.
                __906_______PutItem_________Write_an_item_to_the_stream.___________________________________________________________*
 *___________
                21.11.3          TResourceCollection.KeyOf

    Synopsis:    Return the key of an item in the collection.

Declaration:     function  KeyOf(Item:  Pointer)  :  Pointer;    Virtual

    Visibility:   default

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 (925  )
                21.11.4          TResourceCollection.GetItem

    Synopsis:    Read an item from the stream.

Declaration:     function  GetItem(var  S:  TStream)  :  Pointer;    Virtual

    Visibility:   default

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 (876  ) method.

       Errors:   Errors returned are those by TStream.Read (923  )

    See also:    TCollection.Load (876  ), TStream.Read (923  )
                21.11.5          TResourceCollection.FreeItem

    Synopsis:    Release memory occupied by item.

Declaration:     procedure  FreeItem(Item:  Pointer);    Virtual

    Visibility:   default

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 (885  )
                                                                                 905

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.11.6          TResourceCollection.PutItem

    Synopsis:    Write an item to the stream.

Declaration:     procedure  PutItem(var  S:  TStream;Item:  Pointer);    Virtual

    Visibility:   default

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 (889  ) method.

       Errors:   Errors returned are those by TStream.Write (924  ).

    See also:    TCollection.Store (889  )
                21.12            TResourceFile



                21.12.1          Description

                TResourceFile (906  ) represents the resources in a binary file image.
                21.12.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  907       Count            Number of resources in the file
                  908       Delete           Delete a resource from the file
                  907       Done             Destroy the instance and remove it from memory.
                  908       Flush            Writes the resources to the stream.
                  907       Get              Return a resource by key name.
                  906       Init             Instantiate a new instance.
                  907       KeyAt            Return the key of the item at a certain position.
                  908       Put              Set a resource by key name.
                __908_______SwitchTo_________Write_resources_to_a_new_stream.______________________________________________________*
 *___________
                21.12.3          TResourceFile.Init

    Synopsis:    Instantiate a new instance.

Declaration:     constructor  Init(AStream:  PStream)

    Visibility:   default

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:    TResourceFile.Done (907  )



                                                                                 906

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.12.4          TResourceFile.Done

    Synopsis:    Destroy the instance and remove it from memory.

Declaration:     destructor  Done;    Virtual

    Visibility:   default

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:    TResourceFile.Init (906  )
                21.12.5          TResourceFile.Count

    Synopsis:    Number of resources in the file

Declaration:     function  Count  :  Sw_Integer

    Visibility:   default

Description:     Count returns the number of resources.  If no resources were read, zero is returned.

       Errors:   None.

    See also:    TResourceFile.Init (906  )
                21.12.6          TResourceFile.KeyAt

    Synopsis:    Return the key of the item at a certain position.

Declaration:     function  KeyAt(I:  Sw_Integer)  :  String

    Visibility:   default

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:    TResourceFile.Get (907  )
                21.12.7          TResourceFile.Get

    Synopsis:    Return a resource by key name.

Declaration:     function  Get(Key:  String)  :  PObject

    Visibility:   default

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



                                                                                 907

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.12.8          TResourceFile.SwitchTo

    Synopsis:    Write resources to a new stream.

Declaration:     function  SwitchTo(AStream:  PStream;Pack:  Boolean)  :  PStream

    Visibility:   default

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 (923  ) and TStream.Write (924  ).

    See also:    TResourceFile.Flush (908  )
                21.12.9          TResourceFile.Flush

    Synopsis:    Writes the resources to the stream.

Declaration:     procedure  Flush

    Visibility:   default

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 (922  ) and TStream.Write (924  ).

    See also:    TResourceFile.SwitchTo (908  )
                21.12.10           TResourceFile.Delete

    Synopsis:    Delete a resource from the file

Declaration:     procedure  Delete(Key:  String)

    Visibility:   default

Description:     Delete deletes the resource identified by Key from the collection.  It sets the Modified flag
                to true.

       Errors:   None.

    See also:    TResourceFile.Flush (908  )
                21.12.11           TResourceFile.Put

    Synopsis:    Set a resource by key name.

Declaration:     procedure  Put(Item:  PObject;Key:  String)

    Visibility:   default

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.



                                                                                 908

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
       Errors:   Errors returned may be those by TStream.Put (922  ) and TStream.Seek

    See also:    TResourceFile.Get (907  )
                21.13            TSortedCollection



                21.13.1          Description

                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 (911  ) method.

                Because the collection is ordered, TSortedCollection overrides some TCollection methods,
                to provide faster routines for lookup.

                The Compare (911  ) 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.

                The example below defines a descendent of  TSortedCollection which is used in the exam-
                ples.
                21.13.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  911       Compare          Compare two items in the collection.
                  910       IndexOf          Return index of an item in the collection.
                  909       Init             Instantiates a new instance of a TSortedCollection
                  913       Insert           Insert new item in collection.
                  910       KeyOf            Return the key of an item
                  910       Load             Instantiates a new instance of a TSortedCollection and loads it from
                                             stream.
                  911       Search           Search for item with given key.
                __914_______Store____________Write_the_collection_to_the_stream.___________________________________________________*
 *___________
                21.13.3          TSortedCollection.Init

    Synopsis:    Instantiates a new instance of a TSortedCollection

Declaration:     constructor  Init(ALimit:  Sw_Integer;ADelta:  Sw_Integer)

    Visibility:   default

Description:     Init  calls  the  inherited  constuctor  (see  TCollection.Init  (875  ))  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:    TSortedCollection.Load (910  ), TCollection.Done (877  )
                                                                                 909

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.13.4          TSortedCollection.Load

    Synopsis:    Instantiates a new instance of a TSortedCollection and loads it from stream.

Declaration:     constructor  Load(var  S:  TStream)

    Visibility:   default

Description:     Load calls the inherited constuctor (see TCollection.Load (876  )) 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.

                For an example, see TCollection.Load (876  ).

       Errors:   None.

    See also:    TSortedCollection.Init (909  ), TCollection.Done (877  )
                21.13.5          TSortedCollection.KeyOf

    Synopsis:    Return the key of an item

Declaration:     function  KeyOf(Item:  Pointer)  :  Pointer;    Virtual

    Visibility:   default

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:    TSortedCollection.IndexOf (910  ), TSortedCollection.Compare (911  )
                21.13.6          TSortedCollection.IndexOf

    Synopsis:    Return index of an item in the collection.

Declaration:     function  IndexOf(Item:  Pointer)  :  Sw_Integer;    Virtual

    Visibility:   default

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.

                For an example, see TCollection.IndexOf (878  )

       Errors:   None.

    See also:    TSortedCollection.Search (911  ), TSortedCollection.Compare (911  )


                                                                                 910

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.13.7          TSortedCollection.Compare

    Synopsis:    Compare two items in the collection.

Declaration:     function  Compare(Key1:  Pointer;Key2:  Pointer)  :  Sw_Integer;    Virtual

    Visibility:   default

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 (911  ) method and
                in the Insert (913  ) 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:    TSortedCollection.IndexOf (910  ), TSortedCollection.Search (911  )


                Listing:  ./objectex/mysortc.pp
                ___________________________________________________________________________________________________________________*
 *___________
                 U n i t 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 O b j e c t( T S o r t e d C o l l e c t i)o n
                             F u n c t i o nCompare       ( 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 nT M y S o r t e d C o l l e c t i o.nCompare     ( Key1   ,Key2     :   P o i n t e r)  :s w _i n t*
 * e g e r;


                 b e g i n
                    Compare     :=  P M y o b j e c(tKey1   ) ^ .G e t F i e l d -  PMyObject       ( Key2   ) ^ .G e t F i e l d;
                end   ;


                end___.____________________________________________________________________________________________________________*
 *___________

                21.13.8          TSortedCollection.Search

    Synopsis:    Search for item with given key.

Declaration:     function  Search(Key:  Pointer;var  Index:  Sw_Integer)  :  Boolean;    Virtual

    Visibility:   default


                                                                                 911

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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  (911  )  function  to  implement  this
                search.

                If the item is found, Search returns True, otherwise False is returned.

       Errors:   None.

    See also:    TCollection.IndexOf (878  )


                Listing:  ./objectex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 6 ;


                {   Program       t o  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     ;
                  {   F o r  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;


                 P r o c e d u r eP 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 o,nI n i(t1 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 g1 0 0  r e c o r d s a t  random      p l a c e s. ') ;
                    For    I : = 1  t o  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   ;
                   M  := New  ( PMyObject       , I n i t) ;
                    Repeat     ;
                       Write      ( 'V a l u e  t o  s e a r c h  f o r ( - 1  s t o p s)  :  ') ;
                        r e a d ( I ) ;
                        I f  I<>-1     then
                           b e g i n
                          M  ^ .S e t F i e l d(i ) ;
                           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;



                                                                                 912

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    D i s p o s e(M ,Done    ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.13.9          TSortedCollection.Insert

    Synopsis:    Insert new item in collection.

Declaration:     procedure  Insert(Item:  Pointer);    Virtual

    Visibility:   default

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 (888  ), 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:    TCollection.AtInsert (888  )


                Listing:  ./objectex/ex35.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 5 ;


                {   Program       t o  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     ;
                  {   F o r  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;


                 P r o c e d u r eP 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 o,nI n i(t1 2 0 , 1 0 ) ) ;
                    W r i t e l n ( ' I n s e r t i n g1 0 0  r e c o r d s a t  random      p l a c e s. ') ;
                    For    I : = 1  t o  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                 913

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.13.10           TSortedCollection.Store

    Synopsis:    Write the collection to the stream.

Declaration:     procedure  Store(var  S:  TStream)

    Visibility:   default

Description:     Store writes the collection to the stream S. It does this by calling the inherited TCollec-
                tion.Store (889  ), and then writing the Duplicates flag to the stream.

                After a Store, the collection can be loaded from the stream with the constructor Load (910  )

                For an example, see TCollection.Load (876  ).

       Errors:   Errors can be those of TStream.Put (922  ).

    See also:    TSortedCollection.Load (910  )
                21.14            TStrCollection



                21.14.1          Description

                The TStrCollection object manages a sorted collection of null-terminated strings (pchar
                strings).  To this end, it overrides the Compare (911  ) method of  TSortedCollection, and
                it introduces methods to read/write strings from a stream.
                21.14.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  914       Compare          Compare two strings in the collection.
                  915       FreeItem         Free null-terminated string from the collection.
                  915       GetItem          Read a null-terminated string from the stream.
                __916_______PutItem__________Write_a_null-terminated_string_to_the_stream._________________________________________*
 *___________
                21.14.3          TStrCollection.Compare

    Synopsis:    Compare two strings in the collection.

Declaration:     function  Compare(Key1:  Pointer;Key2:  Pointer)  :  Sw_Integer;    Virtual

    Visibility:   default

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.

                0 if the two strings are equal.

                1 if the first string is alphabetically later than the second string.


       Errors:   None.

    See also:    TSortedCollection.Compare (911  )


                Listing:  ./objectex/ex38.pp


                                                                                 914

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 8 ;


                {   Program       t o  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   :  P c h a r;


                 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 g1 0 0  r e c o r d s a t  random      p l a c e s. ') ;
                    For    I : = 1  t o  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  t o  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___.____________________________________________________________________________________________________________*
 *___________

                21.14.4          TStrCollection.GetItem

    Synopsis:    Read a null-terminated string from the stream.

Declaration:     function  GetItem(var  S:  TStream)  :  Pointer;    Virtual

    Visibility:   default

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 (917  ).

    See also:    TStrCollection.PutItem (916  )
                21.14.5          TStrCollection.FreeItem

    Synopsis:    Free null-terminated string from the collection.

Declaration:     procedure  FreeItem(Item:  Pointer);    Virtual

    Visibility:   default

Description:     TStrCollection overrides FreeItem so that the string pointed to by Item is disposed from
                memory.



                                                                                 915

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
       Errors:   None.

    See also:    TCollection.FreeItem (885  )
                21.14.6          TStrCollection.PutItem

    Synopsis:    Write a null-terminated string to the stream.

Declaration:     procedure  PutItem(var  S:  TStream;Item:  Pointer);    Virtual

    Visibility:   default

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 (922  ).

    See also:    TStrCollection.GetItem (915  )
                21.15            TStream



                21.15.1          Description

                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 descendent types.

                Programs should not instantiate objects of type TStream directly, but instead instantiate a
                descendant type, such as TDosStream, TMemoryStream.
                21.15.2          Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  920       Close              Close the stream
                  924       CopyFrom           Copy data from another stream.
                  923       Error              Set stream status
                  921       Flush              Flush the stream data from the buffer, if any.
                  917       Get                Read an object definition from the stream.
                  918       GetPos             Return current position in the stream
                  919       GetSize            Return the size of the stream.
                  917       Init               Constructor for TStream instance
                  920       Open               Open the stream
                  922       Put                Write an object to the stream.
                  923       Read               Read data from stream to buffer.
                  919       ReadStr            Read a shortstring from the stream.
                  921       Reset              Reset the stream
                  922       Seek               Set stream position.
                  917       StrRead            Read a null-terminated string from the stream.
                  922       StrWrite           Write a null-terminated string to the stream.
                  921       Truncate           Truncate the stream size on current position.
                  924       Write              Write a number of bytes to the stream.
                __922_______WriteStr___________Write_a_pascal_string_to_the_stream.________________________________________________*
 *___________



                                                                                 916

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.15.3          TStream.Init

    Synopsis:    Constructor for TStream instance

Declaration:     constructor  Init

    Visibility:   default

Description:     Init initializes a TStream instance.  Descendent streams should always call the inherited
                Init.
                21.15.4          TStream.Get

    Synopsis:    Read an object definition from the stream.

Declaration:     function  Get  :  PObject

    Visibility:   default

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:    TStream.Put (922  )


                Listing:  ./objectex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 9 ;


                {   Program       t o  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      }


                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 S t r e a m i s  an    a b s t r a c tt 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 go 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___.____________________________________________________________________________________________________________*
 *___________

                21.15.5          TStream.StrRead

    Synopsis:    Read a null-terminated string from the stream.

Declaration:     function  StrRead  :  PChar



                                                                                 917

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
    Visibility:  default

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:    TStream.StrWrite (922  ), TStream.ReadStr (919  )


                Listing:  ./objectex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 0 ;


                {
                Program        t o  d e m o n s t r a t et h e  TStream     . S t r R e a dTStream      . S t r W r i t ef 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 P c h a r s t r i n g' ;
                    W r i t e l n ( ' W r i t i n gt o   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 e(P ) ;
                    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     f r o m  s t r e a m :  "  ',P  , '" ' ) ;
                    Freemem     ( P , S t r l e n(P) + 1 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.15.6          TStream.GetPos

    Synopsis:    Return current position in the stream

Declaration:     function  GetPos  :  LongInt;    Virtual

    Visibility:   default

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:    TStream.Seek (922  ), TStream.GetSize (919  )


                Listing:  ./objectex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 1 ;


                {   Program       t o  d e m o n s t r a t et h e  TStream     . G e t P o s f u n c t i o n }


                Uses     o b j e c t s;

                                                                                 918

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                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 ( 'S t r e a m  p o s i t i o nb e f o r e  w r i t e:  ' ,S ^ .G e t P o s) ;
                    S ^ .W r i t e S t r(@L  ) ;
                    W r i t e l n ( 'S t r e a m  p o s i t i o n a f t e r w r i t e :   ' ,S ^ .G e t P o s) ;
                    D i s p o s e(S ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.15.7          TStream.GetSize

    Synopsis:    Return the size of the stream.

Declaration:     function  GetSize  :  LongInt;    Virtual

    Visibility:   default

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:    TStream.Seek (922  ), TStream.GetPos (918  )


                Listing:  ./objectex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 2 ;


                {   Program       t o  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 ( 'S t r e a m  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 ( 'S t r e a m  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___.____________________________________________________________________________________________________________*
 *___________

                21.15.8          TStream.ReadStr

    Synopsis:    Read a shortstring from the stream.

Declaration:     function  ReadStr  :  PString

    Visibility:   default

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.



                                                                                 919

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
       Errors:   On error (e.g.  not enough memory), Nil is returned.

    See also:    TStream.StrRead (917  )


                Listing:__./objectex/ex13.pp_______________________________________________________________________________________*
 *___________

                Program       e x 1 3 ;


                {
                Program        t o  d e m o n s t r a t et h e  TStream     . R e a d S t rTStream      . W r i t e S t rf 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 gt o   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(rP ) ;
                    DisPose       (S  ,Done   ) ;
                    W r i t e l n ( 'Read     f r o m  s t r e a m :  "  ', L , '" ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.15.9          TStream.Open

    Synopsis:    Open the stream

Declaration:     procedure  Open(OpenMode:  Word);    Virtual

    Visibility:   default

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.

                For an example, see TDosStream.Open (893  ).

       Errors:   None.

    See also:    TStream.Close (920  ), TStream.Reset (921  )
                21.15.10           TStream.Close

    Synopsis:    Close the stream

Declaration:     procedure  Close;    Virtual

    Visibility:   default

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.

                for an example, see TDosStream.Open (893  ).



                                                                                 920

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
       Errors:   None.

    See also:    TStream.Open (920  ), TStream.Reset (921  )
                21.15.11           TStream.Reset

    Synopsis:    Reset the stream

Declaration:     procedure  Reset

    Visibility:   default

Description:     Reset sets the stream's status to 0, as well as the ErrorInfo

       Errors:   None.

    See also:    TStream.Open (920  ), TStream.Close (920  )
                21.15.12           TStream.Flush

    Synopsis:    Flush the stream data from the buffer, if any.

Declaration:     procedure  Flush;    Virtual

    Visibility:   default

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.

                for an example, see TBufStream.Flush (872  ).

       Errors:   None.

    See also:    TStream.Truncate (921  )
                21.15.13           TStream.Truncate

    Synopsis:    Truncate the stream size on current position.

Declaration:     procedure  Truncate;    Virtual

    Visibility:   default

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.

                For an example, see TDosStream.Truncate (891  ).

       Errors:   None.

    See also:    TStream.Seek (922  )

                                                                                 921

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.15.14           TStream.Put

    Synopsis:    Write an object to the stream.

Declaration:     procedure  Put(P:  PObject)

    Visibility:   default

Description:     Put writes the object pointed to by P. P should be non-nil.  The object type must have been
                registered with RegisterType (869  ).

                After the object has been written, it can be read again with Get (917  ).

                For an example, see TStream.Get (917  );

       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:    TStream.Get (917  )
                21.15.15           TStream.StrWrite

    Synopsis:    Write a null-terminated string to the stream.

Declaration:     procedure  StrWrite(P:  PChar)

    Visibility:   default

Description:     StrWrite writes the null-terminated string P to the stream.  P can only be 65355 bytes long.

                For an example, see TStream.StrRead (917  ).

       Errors:   None.

    See also:    TStream.WriteStr (922  ), TStream.StrRead (917  ), TStream.ReadStr (919  )
                21.15.16           TStream.WriteStr

    Synopsis:    Write a pascal string to the stream.

Declaration:     procedure  WriteStr(P:  PString)

    Visibility:   default

Description:     StrWrite writes the pascal string pointed to by P to the stream.

                For an example, see TStream.ReadStr (919  ).

       Errors:   None.

    See also:    TStream.StrWrite (922  ), TStream.StrRead (917  ), TStream.ReadStr (919  )
                21.15.17           TStream.Seek

    Synopsis:    Set stream position.

Declaration:     procedure  Seek(Pos:  LongInt);    Virtual

    Visibility:   default

                                                                                 922

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
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)

                For an example, see TDosStream.Seek (892  ).

       Errors:   If  Pos is larger than the stream size, Status is set to StSeekError.

    See also:    TStream.GetPos (918  ), TStream.GetSize (919  )
                21.15.18           TStream.Error

    Synopsis:    Set stream status

Declaration:     procedure  Error(Code:  Integer;Info:  Integer);    Virtual

    Visibility:   default

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.
                21.15.19           TStream.Read

    Synopsis:    Read data from stream to buffer.

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

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:    TStream.Write (924  ), TStream.ReadStr (919  ), TStream.StrRead (917  )


                Listing:  ./objectex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x 1 8 ;


                {   Program       t o  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     :  A r r a y[ 1 . . 1 0 0 0 ] o f  B y t e;
                        I  :   l o n g i n t;
                       S   :  PMemorySTream          ;


                 b e g i n
                    For    I : = 1  t o  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   ) ) ;



                                                                                 923

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    S ^ .Seek   ( 0 ) ;
                    For    I : = 1  t o  1 0 0 0 do
                       Buf1    [I ] : = 0 ;
                    S ^ .Read   ( Buf1   , S i z e O f(Buf1   ) ) ;
                    For    I : = 1  t o  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___.____________________________________________________________________________________________________________*
 *___________

                21.15.20           TStream.Write

    Synopsis:    Write a number of bytes to the stream.

Declaration:     procedure  Write(var  Buf;Count:  LongInt);    Virtual

    Visibility:   default

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.

                For an example, see TStream.Read (923  ).

       Errors:   No checking is done to see if  Buf actually contains Count bytes.

    See also:    TStream.Read (923  ), TStream.WriteStr (922  ), TStream.StrWrite (922  )
                21.15.21           TStream.CopyFrom

    Synopsis:    Copy data from another stream.

Declaration:     procedure  CopyFrom(var  S:  TStream;Count:  LongInt)

    Visibility:   default

Description:     CopyFrom reads Count bytes from stream S and stores them in the current stream.  It uses
                the Read (923  ) method to read the data, and the Write (924  ) method to write in the current
                stream.

       Errors:   None.

    See also:    TStream.Read (923  ), TStream.Write (924  )


                Listing:  ./objectex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 1 9 ;


                {   Program       t o  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' ;



                                                                                 924

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                    W r i t e l n ( ' W r i t i n gt o   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 so f  s t r e a m 1   t 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(rP ) ;
                    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     f r o m  s t r e a m 2  :  "  ' ,L , '"  ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                21.16            TStringCollection



                21.16.1          Description

                The TStringCollection object manages a sorted collection of pascal strings.  To this end,
                it overrides the Compare (911  ) method of  TSortedCollection, and it introduces methods
                to read/write strings from a stream.
                21.16.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  925       Compare          Compare two strings in the collection.
                  926       FreeItem         Dispose a string in the collection from memory.
                  925       GetItem          Get string from the stream.
                __927_______PutItem__________Write_a_string_to_the_stream._________________________________________________________*
 *___________
                21.16.3          TStringCollection.GetItem

    Synopsis:    Get string from the stream.

Declaration:     function  GetItem(var  S:  TStream)  :  Pointer;    Virtual

    Visibility:   default

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 (919  ).

    See also:    TStringCollection.PutItem (927  )
                21.16.4          TStringCollection.Compare

    Synopsis:    Compare two strings in the collection.

Declaration:     function  Compare(Key1:  Pointer;Key2:  Pointer)  :  Sw_Integer;    Virtual



                                                                                 925

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
    Visibility:  default

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 (911  )


                Listing:  ./objectex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 7 ;


                {   Program       t o  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 o.nCompare     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 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 g1 0 0  r e c o r d s a t  random      p l a c e s. ') ;
                    For    I : = 1  t o  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  t o  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 es 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___.____________________________________________________________________________________________________________*
 *___________

                21.16.5          TStringCollection.FreeItem

    Synopsis:    Dispose a string in the collection from memory.

Declaration:     procedure  FreeItem(Item:  Pointer);    Virtual

    Visibility:   default

Description:     TStringCollection overrides FreeItem so that the string pointed to by Item is disposed
                from memory.

       Errors:   None.

    See also:    TCollection.FreeItem (885  )



                                                                                 926

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.16.6          TStringCollection.PutItem

    Synopsis:    Write a string to the stream.

Declaration:     procedure  PutItem(var  S:  TStream;Item:  Pointer);    Virtual

    Visibility:   default

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 (922  ).

    See also:    TStringCollection.GetItem (925  )
                21.17            TStringList



                21.17.1          Description

                A  TStringList  object  can  be  used  to  read  a  collection  of  strings  stored  in  a  stream.
                If  you  register  this  object  with  the  RegisterType  (869  )  function,  you  cannot  register  the
                TStrListMaker object.
                21.17.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  927       Done            Clean up the instance
                  928       Get             Return a string by key name
                __927_______Load____________Load_stringlist_from_stream.___________________________________________________________*
 *___________
                21.17.3          TStringList.Load

    Synopsis:    Load stringlist from stream.

Declaration:     constructor  Load(var  S:  TStream)

    Visibility:   default

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:    TStringList.Done (927  )
                21.17.4          TStringList.Done

    Synopsis:    Clean up the instance

Declaration:     destructor  Done;    Virtual

    Visibility:   default

                                                                                 927

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
Description:     The Done destructor frees the memory occupied by the string descriptions, and destroys the
                object.

       Errors:   None.

    See also:    TStringList.Load (927  ), TObject.Done (898  )
                21.17.5          TStringList.Get

    Synopsis:    Return a string by key name

Declaration:     function  Get(Key:  Sw_Word)  :  String

    Visibility:   default

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 (929  )
                21.18            TStrListMaker



                21.18.1          Description

                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 (869  )
                function, you cannot register the TStringList object.
                21.18.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  929       Done            Clean up the instance and free all related memory.
                  928       Init            Instantiate a new instance of  TStrListMaker
                  929       Put             Add a new string to the list with associated key.
                __929_______Store___________Write_the_strings_to_the_stream._______________________________________________________*
 *___________
                21.18.3          TStrListMaker.Init

    Synopsis:    Instantiate a new instance of  TStrListMaker

Declaration:     constructor  Init(AStrSize:  Sw_Word;AIndexSize:  Sw_Word)

    Visibility:   default

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 (897  ), TStrListMaker.Done (929  )



                                                                                 928

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.18.4          TStrListMaker.Done

    Synopsis:    Clean up the instance and free all related memory.

Declaration:     destructor  Done;    Virtual

    Visibility:   default

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 (898  ), TStrListMaker.Init (928  )
                21.18.5          TStrListMaker.Put

    Synopsis:    Add a new string to the list with associated key.

Declaration:     procedure  Put(Key:  Sw_Word;S:  String)

    Visibility:   default

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 (929  ) method.

       Errors:   None.

    See also:    TStrListMaker.Store (929  )
                21.18.6          TStrListMaker.Store

    Synopsis:    Write the strings to the stream.

Declaration:     procedure  Store(var  S:  TStream)

    Visibility:   default

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 (927  ), TStrListMaker.Put (929  )
                21.19            TUnSortedStrCollection



                21.19.1          Description

                The  TUnSortedStrCollection  object  manages  an  unsorted  list  of  strings.   To  this  end,
                it  overrides  the  TStringCollection.Insert  (925  )  method  to  add  strings  at  the  end  of  the
                collection, rather than in the alphabetically correct position.

                Take care, the Search (911  ) and IndexOf (878  ) methods will not work on an unsorted string
                collection.

                                                                                 929

                ________________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________
                21.19.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __930_______Insert__________Insert_a_new_string_in_the_collection._________________________________________________*
 *___________
                21.19.3          TUnSortedStrCollection.Insert

    Synopsis:    Insert a new string in the collection.

Declaration:     procedure  Insert(Item:  Pointer);    Virtual

    Visibility:   default

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:   None.

    See also:    TCollection.Insert (884  )


                Listing:  ./objectex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 3 9 ;


                {   Program       t o  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 tmethod      }


                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   :  P c h a r;


                 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 g1 0 0  r e c o r d s a t  random      p l a c e s. ') ;
                    For    I : = 1  t o  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  t o  9 9  do
                        W r i t e l n( I : 2 , ':   ', P S t r i n g(C ^ .At  ( i) ) ^  ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 930


Chapter   22


Reference   for   unit   'ob jpas'
22.1          Overview


The objpas unit is meant for compatibility with Object Pascal as implemented by Delphi.
The unit is loaded automatically by the Free Pascal compiler whenever the Delphi or objfpc
more is entered, either through the command line switches -Sd or -Sh or with the {$MODE
DELPHI} or {$MODE  OBJFPC} directives.

It redefines some basic pascal types, introduces some functions for compatibility with Delphi's
system unit, and introduces some methods for the management of the resource string tables.
22.2          Constants,  types  and  variables



22.2.1         Constants

MaxInt  =  MaxLongint


Maximum value for Integer (931  ) type.
22.2.2         Types

Integer  =  LongInt


In  OBJPAS  mode  and  in  DELPHI  mode,  an  Integer  has  a  size  of  32  bit.  In  TP  or  regular
FPC mode, an integer is 16 bit.


IntegerArray  =  Array[0..$effffff]  of  Integer


Generic array of integer (931  )


PInteger  =  ^Integer


Pointer to Integer (931  ) type.


PIntegerArray  =  ^IntegerArray


Pointer to TIntegerArray (932  ) type.



                                                             931

__________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________________________*
 *___
PointerArray  =  Array[0..512*1024*1024-2]  of  Pointer


Generic Array of pointers.


PPointerArray  =  ^PointerArray


Pointer to PointerArray (932  )


PResStringRec  =  ^AnsiString


Pointer to ansistring (Delphi compatibility).


PString  =  PAnsiString


Pointer to ansistring type.


TBoundArray  =  Array  of  Integer


Array of integer, used in interfaces.


TIntegerArray  =  IntegerArray


Alias for IntegerArray (931  )


TPointerArray  =  PointerArray


Alias for PointerArray (932  )


TResourceIterator  =  function(Name:  AnsiString;Value:  AnsiString;
                                               Hash:  LongInt;arg:  pointer)  :  AnsiString


The  resource  string  tables  can  be  managed  with  a  callback  function  which  the  user  must
provide:  TResourceIterator.


TResStringRec  =  AnsiString


Ansistring record in resource table (Delphi compatibility).
22.2.3         Variables

ExceptionClass  :  TClass


ExceptionClass  is  the  base  class  for  all  exceptions.   Normally,  this  is  Exception  (1505   ),
definied in the Sysutils (1356   ) unit.


ExceptObjProc  :  Pointer


ExceptObjProc is unused in Free Pascal, and is provided for Delphi compatibility only.


                                                                 932

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
                22.3          Procedures  and  functions



                22.3.1         AssignFile

    Synopsis:    Assign text or untyped file

Declaration:     procedure  AssignFile(var  f:  File;const  Name:  String)
                procedure  AssignFile(var  f:  File;p:  pchar)
                procedure  AssignFile(var  f:  File;c:  Char)
                procedure  AssignFile(var  t:  Text;const  s:  String)
                procedure  AssignFile(var  t:  Text;p:  pchar)
                procedure  AssignFile(var  t:  Text;c:  Char)
                procedure  AssignFile(var  f:  TypedFile;const  Name:  String)
                procedure  AssignFile(var  f:  TypedFile;p:  pchar)
                procedure  AssignFile(var  f:  TypedFile;c:  Char)

    Visibility:   default

Description:     AssignFile is completely equivalent to the system unit's Assign (1216   ) function:  It assigns
                Name to a function of any type (FileType can be Text or a typed or untyped File variable).
                Name can be a string, a single character or a PChar.

                It is most likely introduced to avoid confusion between the regular Assign (1216   ) function
                and the Assign method of  TPersistent in the Delphi VCL.

       Errors:   None.

    See also:    CloseFile (933  ), #rtl.system.Assign (1216   ), #rtl.system.Reset (1308   ), #rtl.system.Rewrite
                (1310   ), #rtl.system.Append (1214   )


                Listing:  ./refex/ex88.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 8;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n F i l eand    C l o s e F i l e f u n c t i o n s. }


                { $MODE      D e l p h i}


                Var    F   :   t e x t;


                 b e g i n
                    A s s i g n F i l(eF , ' t e x t f i l e.tmp  ') ;
                    R e w r i t e(F ) ;
                    W r i t e l n (F  , 'T h i s  i s  a   s i l l y e x a m p l e o f  A s s i g n F i l eand    C l o s e F i l e*
 *.' ) ;
                    C l o s e F i l e(F) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.2         CloseFile

    Synopsis:    Close text or untyped file

Declaration:     procedure  CloseFile(var  f:  File)
                procedure  CloseFile(var  t:  Text)

    Visibility:   default



                                                                                 933

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
Description:     CloseFile flushes and closes a file F of any file type.  F can be Text or a typed or untyped
                File variable.  After a call to CloseFile, any attempt to write to the file F will result in an
                error.

                It is most likely introduced to avoid confusion between the regular Close (1223   ) function and
                the Close method of  TForm in the Delphi VCL.

                for an example, see AssignFile (933  ).

       Errors:   None.

    See also:    #rtl.system.Close (1223   ), AssignFile (933  ), #rtl.system.Reset (1308   ), #rtl.system.Rewrite
                (1310   ), #rtl.system.Append (1214   )
                22.3.3         FinalizeResourceTables

    Synopsis:    Finalize resource string tables

Declaration:     procedure  FinalizeResourceTables

    Visibility:   default

Description:     FinalizeResourceTables should be called by any routine that sets the resource string ta-
                bles to translated versions of the strings.  Typically, it should be called in the Finalization
                code of the unit that does the initialization of the tables.  This is needed to correctly deallo-
                cate the strings from memory
                22.3.4         GetResourceStringCurrentValue

    Synopsis:    Return current value of resourcestring

Declaration:     function  GetResourceStringCurrentValue(TableIndex:  LongInt;
                                                                               StringIndex:  LongInt)  :  AnsiString

    Visibility:   default

Description:     GetResourceStringCurrentValue returns the current value of the resourcestring in table
                TableIndex with index StringIndex.

                The current value depends on the system of internationalization that was used, and which
                language is selected when the program is executed.

       Errors:   If either TableIndex or StringIndex are out of range, then a empty string is returned.

    See also:    SetResourceStrings  (939  ),  GetResourceStringDefaultValue  (935  ),  GetResourceStringHash
                (935  ), GetResourceStringName (936  ), ResourceStringTableCount (939  ), ResourceStringCount
                (938  )


                Listing:  ./refex/ex90.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 0;


                {   Program       t o  d e m o n s t r a t et h e  G e t R e s o u r c e S t r i n g C u r r e n t V a lfuuen c t i*
 * o n. }
                { $Mode      D e l p h i}


                 R e s o u r c e S t r i n g


                    F i r s t   =   ' F i r s t s t r i n g';
                    S e c o n d =   'S e c o n d  S t r i n g';



                                                                                 934

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________


                Var     I, J   :  L o n g i n t;


                 b e g i n
                    {   P r i n t c u r r e n t v a l u e s o f   a l l  r e s o u r c e s t r i n g}s
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           W r i t e l n ( I , ', ' ,J , '  :   ' ,G e t R e s o u r c e S t r i n g C u r r e n t V a(lIu,eJ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.5         GetResourceStringDefaultValue

    Synopsis:    Return default (original) value of resourcestring

Declaration:     function  GetResourceStringDefaultValue(TableIndex:  LongInt;
                                                                               StringIndex:  LongInt)  :  AnsiString

    Visibility:   default

Description:     GetResourceStringDefaultValue returns the default value of the resourcestring in table
                TableIndex with index StringIndex.

                The default value is the value of the string that appears in the source code of the programmer,
                and is compiled into the program.

       Errors:   If either TableIndex or StringIndex are out of range, then a empty string is returned.

    See also:    SetResourceStrings  (939  ),  GetResourceStringCurrentValue  (934  ),  GetResourceStringHash
                (935  ), GetResourceStringName (936  ), ResourceStringTableCount (939  ), ResourceStringCount
                (938  )


                Listing:  ./refex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 1;


                {   Program       t o  d e m o n s t r a t et h e  G e t R e s o u r c e S t r i n g D e f a u l t V a lfuuen c t i*
 * o n. }
                { $Mode      D e l p h i}


                 R e s o u r c e S t r i n g


                    F i r s t   =   ' F i r s t s t r i n g';
                    S e c o n d =   'S e c o n d  S t r i n g';


                Var     I, J   :  L o n g i n t;


                 b e g i n
                    {   P r i n t d e f a u l t v a l u e s o f   a l l  r e s o u r c e s t r i n g}s
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           W r i t e l n ( I , ', ' ,J , '  :   ' ,G e t R e s o u r c e S t r i n g D e f a u l t V a(lIu,eJ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.6         GetResourceStringHash

    Synopsis:    Return hash value of resource string

                                                                                 935

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
Declaration:     function  GetResourceStringHash(TableIndex:  LongInt;StringIndex:  LongInt)
                                                                   :  LongInt

    Visibility:  default

Description:     GetResourceStringHash returns the hash value associated with the resource string in table
                TableIndex, with index StringIndex.

                The hash value is calculated from the default value of the resource string in a manner that
                gives the same result as the GNU gettext mechanism.  It is stored in the resourcestring tables,
                so retrieval is faster than actually calculating the hash for each string.

                For an example, see Hash (937  ).

       Errors:   If either TableIndex or StringIndex is zero, 0 is returned.

    See also:    Hash (937  ), SetResourceStrings (939  ), GetResourceStringDefaultValue (935  ), GetResourceS-
                tringHash (935  ), GetResourceStringName (936  ), ResourceStringTableCount (939  ), ResourceS-
                tringCount (938  )
                22.3.7         GetResourceStringName

    Synopsis:    Return name of resource string.

Declaration:     function  GetResourceStringName(TableIndex:  LongInt;StringIndex:  LongInt)
                                                                   :  Ansistring

    Visibility:   default

Description:     GetResourceStringName returns the name of the resourcestring in table TableIndex with
                index StringIndex.  The name of the string is always the unit name in which the string was
                declared, followed by a period and the name of the constant, all in lowercase.

                If a unit MyUnit declares a resourcestring MyTitle then the name returned will be myunit.mytitle.
                A resourcestring in the program file will have the name of the program prepended.

                The name returned by this function is also the name that is stored in the resourcestring file
                generated by the compiler.

                Strictly speaking,  this information isn't necessary for the functioning of the program,  it is
                provided only as a means to easier translation of strings.

       Errors:   If either TableIndex or StringIndex is zero, an empty string is returned.

    See also:    SetResourceStrings  (939  ),  GetResourceStringDefaultValue  (935  ),  GetResourceStringHash
                (935  ), GetResourceStringName (936  ), ResourceStringTableCount (939  ), ResourceStringCount
                (938  )


                Listing:  ./refex/ex92.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 2;


                {   Program       t o  d e m o n s t r a t et h e  G e t R e s o u r c e S t r i n g N a mfeu n c t i o n. }
                { $Mode      D e l p h i}


                 R e s o u r c e S t r i n g


                    F i r s t   =   ' F i r s t s t r i n g';
                    S e c o n d =   'S e c o n d  S t r i n g';


                Var     I, J   :  L o n g i n t;



                                                                                 936

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________


                 b e g i n
                    {   P r i n t names      o f  a l l  r e s o u r c e s t r i n g}s
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           W r i t e l n ( I , ', ' ,J , '  :   ' ,G e t R e s o u r c e S t r i n g N a(mIe,J ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.8         Hash

    Synopsis:    Create GNU Gettext hash value for a string

Declaration:     function  Hash(S:  AnsiString)  :  LongWord

    Visibility:   default

Description:     Hash calculates the hash value of the string S in a manner that is compatible with the GNU
                gettext hash value for the string.  It is the same value that is stored in the Resource string
                tables, and which can be retrieved with the GetResourceStringHash (935  ) function call.

       Errors:   None.  In case the calculated hash value should be 0, the returned result will be -1.

    See also:    GetResourceStringHash (935  )


                Listing:  ./refex/ex93.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 3;


                {   Program       t o  d e m o n s t r a t et h e  Hash     f u n c t i o n. }
                { $Mode      D e l p h i}


                 R e s o u r c e S t r i n g


                    F i r s t   =   ' F i r s t s t r i n g';
                    S e c o n d =   'S e c o n d  S t r i n g';


                Var     I, J   :  L o n g i n t;


                 b e g i n
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           I f  Hash   ( G e t R e s o u r c e S t r i n g D e f a u l t V a(lIu,eJ) )
                              <>  G e t R e s o u r c e S t r i n g H a(sIh,J )  then
                               W r i t e l n(  'Hash     m i s m a t c ha t   ' ,I , ' ,' ,J )
                           e l s e
                               W r i t e l n(  'Hash    (  ', I , ', ' ,J , ' )  m a t c h e s.' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.9         LoadResString

    Synopsis:    Load resource string

Declaration:     function  LoadResString(p:  PResStringRec)  :  AnsiString

    Visibility:   default

                                                                                 937

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
                22.3.10          ParamStr

    Synopsis:    Return command-line parameter

Declaration:     function  ParamStr(Param:  Integer)  :  Ansistring

    Visibility:   default

Description:     ParamStr  returns  the  Param-th  command-line  parameter  as  an  AnsiString.   The  system
                unit Paramstr (938  ) function limits the result to 255 characters, and is overridden with this
                function.

                The zeroeth command-line parameter contains the path of the executable.  On some operating
                systems (BSD) it may be simply the command as typed on the command-line, because the
                OS does not offer a method to retrieve the full binary name.

                For an example, see #rtl.system.Paramstr (1300   ).

       Errors:   In case Param is an invalid value, an empty string is returned.

    See also:    Paramstr (938  )
                22.3.11          ResetResourceTables

    Synopsis:    Restore all resource strings to their declared values

Declaration:     procedure  ResetResourceTables

    Visibility:   default

Description:     ResetResourceTables resets all resource strings to their default (i.e.  as in the source code)
                values.

                Normally, this should never be called from a user's program.  It is called in the initialization
                code of the objpas unit.  However, if the resourcetables get messed up for some reason, this
                procedure will fix them again.

       Errors:   None.

    See also:    SetResourceStrings  (939  ),  GetResourceStringDefaultValue  (935  ),  GetResourceStringHash
                (935  ), GetResourceStringName (936  ), ResourceStringTableCount (939  ), ResourceStringCount
                (938  )
                22.3.12          ResourceStringCount

    Synopsis:    Return number of resource strins in table

Declaration:     function  ResourceStringCount(TableIndex:  LongInt)  :  LongInt

    Visibility:   default

Description:     ResourceStringCount returns the number of resourcestrings in the table with index TableIndex.
                The  strings  in  a  particular  table  are  numbered  from  0  to  ResourceStringCount-1,  i.e.
                they're zero based.

                For an example, see GetResourceStringDefaultValue (935  )

       Errors:   If an invalid TableIndex is given, -1 is returned.

    See also:    SetResourceStrings (939  ), GetResourceStringCurrentValue (934  ), GetResourceStringDefault-
                Value (935  ), GetResourceStringHash (935  ), GetResourceStringName (936  ), ResourceStringTable-
                Count (939  )



                                                                                 938

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
                22.3.13          ResourceStringTableCount

    Synopsis:    Return number of resource string tables

Declaration:     function  ResourceStringTableCount  :  LongInt

    Visibility:   default

Description:     ResourceStringTableCount returns the number of resource string tables; this may be zero
                if no resource strings are used in a program.

                The tables are numbered from 0 to ResourceStringTableCount-1, i.e.  they're zero based.

                For an example, see GetResourceStringDefaultValue (935  )

       Errors:

    See also:    SetResourceStrings  (939  ),  GetResourceStringDefaultValue  (935  ),  GetResourceStringHash
                (935  ), GetResourceStringName (936  ), ResourceStringCount (938  )
                22.3.14          SetResourceStrings

    Synopsis:    Set values of all resource strings.

Declaration:     procedure  SetResourceStrings(SetFunction:  TResourceIterator;
                                                              arg:  pointer)

    Visibility:   default

Description:     SetResourceStrings calls SetFunction for all resourcestrings in the resourcestring tables
                and sets the resourcestring's current value to the value returned by SetFunction.

                The Name,Value and Hash parameters passed to the iterator function are the values stored
                in the tables.

       Errors:   None.

    See also:    GetResourceStringCurrentValue (934  ), GetResourceStringDefaultValue (935  ), GetResourceS-
                tringHash (935  ), GetResourceStringName (936  ), ResourceStringTableCount (939  ), ResourceS-
                tringCount (938  )


                Listing:  ./refex/ex95.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 5;


                {   Program       t o  d e m o n s t r a t et h e  S e t R e s o u r c e S t r i n gfsu n c t i o n. }
                { $Mode      o b j f p c}


                 R e s o u r c e S t r i n g


                    F i r s t   =   ' F i r s t s t r i n g';
                    S e c o n d =   'S e c o n d  S t r i n g';


                Var     I, J   :  L o n g i n t;
                       S   :   A n s i S t r i n;g


                 F u n c t i o nT r a n s l a t e (Name    ,V a l u e  :  A n s i S t r i n g; Hash     :  l o n g i n t) :  A n s *
 *i S t r i n;g


                 b e g i n
                    W r i t e l n ( ' T r a n s l a t e( ' ,Name   , ')  = >    ', V a l u e) ;
                    Write         ( '->  ' ) ;



                                                                                 939

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
                    Readln        ( R e s u l t) ;
                end   ;


                 b e g i n
                    S e t R e s o u r c e S t r i n(g@sT r a n s l a t e) ;
                    W r i t e l n ( ' T r a n s l a t e ds t r i n g s :  ' ) ;
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           b e g i n
                           W r i t e l n ( G e t R e s o u r c e S t r i n g D e f a u l t V a(lIu,eJ) ) ;
                           W r i t e l n ( ' T r a n s l a t e st o  :   ') ;
                           W r i t e l n ( G e t R e s o u r c e S t r i n g C u r r e n t V a(lIu,eJ) ) ;
                           end  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.15          SetResourceStringValue

    Synopsis:    Set value of a resource string

Declaration:     function  SetResourceStringValue(TableIndex:  LongInt;
                                                                   StringIndex:  LongInt;Value:  Ansistring)
                                                                     :  Boolean

    Visibility:   default

Description:     SetResourceStringValue assigns Value to the resource string in table TableIndex with
                index StringIndex.

       Errors:

    See also:    SetResourceStrings (939  ), GetResourceStringCurrentValue (934  ), GetResourceStringDefault-
                Value (935  ), GetResourceStringHash (935  ), GetResourceStringName (936  ), ResourceStringTable-
                Count (939  ), ResourceStringCount (938  )


                Listing:  ./refex/ex94.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 4;


                {   Program       t o  d e m o n s t r a t et h e  S e t R e s o u r c e S t r i n g V a l ufeu n c t i o.n }
                { $Mode      D e l p h i}


                 R e s o u r c e S t r i n g


                    F i r s t   =   ' F i r s t s t r i n g';
                    S e c o n d =   'S e c o n d  S t r i n g';


                Var     I, J   :  L o n g i n t;
                       S   :   A n s i S t r i n;g


                 b e g i n
                    {   P r i n t c u r r e n t v a l u e s o f   a l l  r e s o u r c e s t r i n g}s
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           b e g i n
                           W r i t e l n ( ' T r a n s l a t e=>   ' , G e t R e s o u r c e S t r i n g D e f a u l t V a(lIu,eJ) *
 *) ;
                           Write         ( '->  ' ) ;
                           Readln    ( S ) ;
                                                                                 940

                __________________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'OBJPAS'________________*
 *___________________
                           S e t R e s o u r c e S t r i n g V a l(uIe,J, S ) ;
                           end  ;
                    W r i t e l n ( ' T r a n s l a t e ds t r i n g s :  ' ) ;
                    For    I : = 0  t o  R e s o u r c e S t r i n g T a b l e C o u-n1tdo
                       For    J : = 0  t o   R e s o u r c e S t r i n g C o u(nit) -1  do
                           b e g i n
                           W r i t e l n ( G e t R e s o u r c e S t r i n g D e f a u l t V a(lIu,eJ) ) ;
                           W r i t e l n ( ' T r a n s l a t e st o  :   ') ;
                           W r i t e l n ( G e t R e s o u r c e S t r i n g C u r r e n t V a(lIu,eJ) ) ;
                           end  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                22.3.16          SetUnitResourceStrings

    Synopsis:    Set unit resource strings for a given unit

Declaration:     procedure  SetUnitResourceStrings(const  UnitName:  String;
                                                                     SetFunction:  TResourceIterator;
                                                                     arg:  pointer)

    Visibility:   default

Description:     SetUnitResourceStrings will call SetFunction for all resource strings of the unit indicated
                by UnitName.  The additional Arg pointer will be passed to the SetFunction iterator.

       Errors:   None.

    See also:    SetResourceStrings (939  ), ResetResourceTables (938  ), FinalizeResourceTables (934  )


                                                                                 941


Chapter   23


Reference   for   unit   'oldlinux'
23.1          Utility  routines


Auxiliary functions that are useful in connection with the other functions.



                                                       Table 23.1:

                __Name________________________________Description______________________________________________
                  CreateShellArgV (1003   )            Create an array of pchars from string
                  EpochToLocal (1006   )               Convert epoch time to local time
                  FD_Clr (1017   )                     Clear item of select filedescriptors
                  FD_IsSet (1018   )                   Check item of select filedescriptors
                  FD_Set (1018   )                     Set item of select filedescriptors
                  FD_ZERO (1018   )                    Clear all items in select filedecriptors
                  LocalToEpoch (1037   )               Convert local time to epoch time
                  MMap (1040   )                       Map a file into memory
                  MUnMap (1041   )                     Unmap previously mapped memory file
                  Octal (1043   )                      Convert octal to digital
                  S_ISBLK (1059   )                    Check file mode for block device
                  S_ISCHR (1060   )                    Check file mode for character device
                  S_ISDIR (1060   )                    Check file mode for directory
                  S_ISFIFO (1060   )                   Check file mode for FIFO
                  S_ISLNK (1060   )                    Check file mode for symboloc link
                  S_ISREG (1061   )                    Check file mode for regular file
                  S_ISSOCK (1061   )                   Check file mode for socket
                  StringToPPchar (1056   )             Create an array of pchars from string



23.2          Terminal  functions


Functions for controlling the terminal to which the process is connected.
23.3          System  information


Functions for retrieving system information such as date and time.



                                                             942

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___

                                                       Table 23.2:

                  _Name_____________________________Description_______________________________________________
                    CFMakeRaw (998  )                Set terminal to raw mode
                    CFSetISpeed (998  )              Set terminal reading speed
                    CFSetOSpeed (999  )              Set terminal writing speed
                    IOCtl (1034   )                  General IO control call
                    IsATTY (1035   )                 See if filedescriptor is a terminal
                    TCDrain (1062   )                Wait till all output was written
                    TCFlow (1062   )                 Suspend transmission or receipt of data
                    TCFlush (1062   )                Discard data written to terminal
                    TCGetAttr (1063   )              Get terminal attributes
                    TCGetPGrp (1063   )              Return PID of foreground process
                    TCSendBreak (1064   )            Send data for specific time
                    TCSetAttr (1064   )              Set terminal attributes
                    TCSetPGrp (1065   )              Set foreground process
                    TTYName (1065   )                Name of tty file

                                                       Table 23.3:

                  _Name____________________________________Description________________________________________
                    GetDate (1024   )                      Return system date
                    GetDateTime (1025   )                  Return system date and time
                    GetDomainName (1025   )                Return system domain name
                    GetEpochTime (1027   )                 Return epoch time
                    GetHostName (1029   )                  Return system host name
                    GetLocalTimezone (1030   )             Return system timezone
                    GetTime (1031   )                      Return system time
                    GetTimeOfDay (1032   )                 Return system time
                    GetTimezoneFile (1032   )              Return name of timezone file
                    ReadTimezoneFile (1048   )             Read timezone file contents
                    SysInfo (1058   )                      Return general system information
                    Uname (1066   )                        Return system information

23.4          Signals


Functions for managing and responding to signals.
23.5          Process  handling


Functions for managing processes and programs.
23.6          Directory  handling  routines


Functions for reading and searching directories.
                                                                 943

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___

                                                       Table 23.4:

                    __Name____________________________Description_________________________________________
                      Alarm (994  )                   Send alarm signal to self
                      Kill (1036   )                  Send arbitrary signal to process
                      pause (1045   )                 Wait for signal to arrive
                      SigAction (1052   )             Set signal action
                      Signal (1053   )                Set signal action
                      SigPending (1054   )            See if signals are waiting
                      SigProcMask (1054   )           Set signal processing mask
                      SigRaise (1055   )              Send signal to self
                      SigSuspend (1056   )            Sets signal mask and waits for signal
                      NanoSleep (1041   )             Waits for a specific amount of time

23.7          Pipes,  FIFOs  and  streams


Functions for creating and managing pipes.
23.8          General  File  handling  routines


Functions for handling files on disk.
23.9          File  Input/Output  routines


Functions for handling file input/output.
23.10            Overview


This document describes the LINUX unit for Free Pascal.  The unit was written by Michael
van Canneyt.  It works only on the Linux/X86 operating system.
23.11            Constants,  types  and  variables



23.11.1          Constants

B0  =  $0000000



B110  =  $0000003



B115200  =  $0001002



B1200  =  $0000009



B134  =  $0000004



                                                                 944

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___

                                                       Table 23.5:

       __Name_________________________Description______________________________________________________________________
         Clone (1001   )              Create a thread
         Execl (1007   )              Execute process with command-line list
         Execle (1008   )             Execute process with command-line list and environment
         Execlp (1009   )             Search in path and execute process with command list
         Execv (1010   )              Execute process
         Execve (1011   )             Execute process with environment
         Execvp (1012   )             Search in path and execute process
         Fork (1020   )               Spawn child process
         GetEGid (1026   )            Get effective group id
         GetEnv (1026   )             Get environment variable
         GetEUid (1027   )            Get effective user id
         GetGid (1029   )             Get group id
         GetPid (1030   )             Get process id
         GetPPid (1030   )            Get parent process id
         GetPriority (1031   )        Get process priority
         GetUid (1033   )             Get user id
         Nice (1042   )               Change priority of process
         SetPriority (1050   )        Change priority of process
         Shell (1051   )              Execute shell command
         WaitPid (1068   )            Wait for child process to terminate

                                                       Table 23.6:

                    __Name______________________Description________________________________________________
                      CloseDir (1003   )        Close directory handle
                      Glob (1033   )            Return files matching a search expression
                      GlobFree (1034   )        Free result of Glob
                      OpenDir (1043   )         Open directory for reading
                      ReadDir (1046   )         Read directory entry
                      SeekDir (1048   )         Seek directory
                      TellDir (1065   )         Seek directory

B150  =  $0000005
B1800  =  $000000A
B19200  =  $000000E
B200  =  $0000006
B230400  =  $0001003
B2400  =  $000000B



                                                                 945

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___

                                                       Table 23.7:

              __Name___________________________Description______________________________________________________
                AssignPipe (995  )             Create a pipe
                AssignStream (996  )           Create pipes to program's input and output
                MkFifo (1039   )               Make a fifo
                PClose (1045   )               Close a pipe
                POpen (1045   )                Open a pipe for to program's input or output

                                                       Table 23.8:

                         __Name_______________________Description____________________________________
                           Access (993  )             Check access rights on file
                           BaseName (997  )           Return name part of file
                           Chown (1000   )            Change owner of file
                           Chmod (999  )              Change access rights on file
                           DirName (1004   )          Return directory part of file
                           FSplit (1022   )           Split filename in parts
                           FExpand (1018   )          Return full-grown filename
                           FLock (1019   )            Set lock on a file
                           FNMatch (1019   )          Match filename to searchpattern
                           FSearch (1021   )          Search for a file in a path
                           FSStat (1022   )           Return filesystem information
                           FStat (1023   )            Return file information
                           FRename (1020   )          Rename file
                           LStat (1038   )            Return information on a link
                           Link (1036   )             Create a link
                           ReadLink (1046   )         Read contents of a symbolic link
                           SymLink (1057   )          Create a symbolic link
                           Umask (1066   )            Set the file creation mask
                           UnLink (1066   )           Remove a file
                           Utime (1067   )            Change file timestamps

B300  =  $0000007



B38400  =  $000000F



B460800  =  $0001004



B4800  =  $000000C



B50  =  $0000001



B57600  =  $0001001



B600  =  $0000008



                                                                 946

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___

                                                       Table 23.9:

                       __Name_________________________Description______________________________________
                         Dup (1005   )                Duplicate a file handle
                         Dup2 (1006   )               Copy one file handle to another
                         Fcntl (1013   )              General file control
                         fdClose (1014   )            Close file descriptor
                         fdFlush (1014   )            Flush file descriptor
                         fdOpen (1014   )             Open new file descriptor
                         fdRead (1015   )             Read from file descriptor
                         fdSeek (1016   )             Position in file
                         fdTruncate (1017   )         Truncate file
                         fdWrite (1017   )            Write to file descriptor
                         GetFS (1028   )              Get file descriptor of pascal file
                         Select (1048   )             Wait for input from file descriptor
                         SelectText (1049   )         Wait for input from pascal file

B75  =  $0000002
B9600  =  $000000D
BRKINT  =  $0000002
BS0  =  $0000000
BS1  =  $0002000
BSDLY  =  $0002000
CBAUD  =  $000100F
CBAUDEX  =  $0001000
CIBAUD  =  $100F0000
CLOCAL  =  $0000800
CLONE_FILES  =  $00000400


Clone (1001   ) option:  open files shared between processes


CLONE_FS  =  $00000200



                                                                 947

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Clone (1001   ) option:  fs info shared between processes


CLONE_PID  =  $00001000


Clone (1001   ) option:  PID shared between processes


CLONE_SIGHAND  =  $00000800


Clone (1001   ) option:  signal handlers shared between processes


CLONE_VM  =  $00000100


Clone (1001   ) option:  VM shared between processes


CMSPAR  =  $40000000
CR0  =  $0000000
CR1  =  $0000200
CR2  =  $0000400
CR3  =  $0000600
CRDLY  =  $0000600
CREAD  =  $0000080
CRTSCTS  =  $80000000
CS5  =  $0000000
CS6  =  $0000010
CS7  =  $0000020
CS8  =  $0000030
CSIGNAL  =  $000000ff


Clone (1001   ) option:  Signal mask to be sent at exit



                                                                 948

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
CSIZE  =  $0000030
CSTOPB  =  $0000040
ECHO  =  $0000008
ECHOCTL  =  $0000200
ECHOE  =  $0000010
ECHOK  =  $0000020
ECHOKE  =  $0000800
ECHONL  =  $0000040
ECHOPRT  =  $0000400
EXTA  =  B19200
EXTB  =  B38400
FF0  =  $0000000
FF1  =  $0008000
FFDLY  =  $0008000
FIOASYNC  =  $5452
FIOCLEX  =  $5451
FIONBIO  =  $5421
FIONCLEX  =  $5450
FIONREAD  =  $541B
                                                                 949

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
FLUSHO  =  $0001000
fs_ext  =  $137d


File system type (FSStat (1022   )):  (ext) Extended


fs_ext2  =  $ef53


File system type (FSStat (1022   )):  (ext2) Second extended


fs_iso  =  $9660


File system type (FSStat (1022   )):  ISO 9660


fs_minix  =  $137f


File system type (FSStat (1022   )):  Minix


fs_minix_30  =  $138f


File system type (FSStat (1022   )):  Minix 3.0


fs_minux_V2  =  $2468


File system type (FSStat (1022   )):  Minix V2


fs_msdos  =  $4d44


File system type (FSStat (1022   )):  MSDOS (FAT)


fs_nfs  =  $6969


File system type (FSStat (1022   )):  NFS


fs_old_ext2  =  $ef51


File system type (FSStat (1022   )):  (ext2) Old second extended


fs_proc  =  $9fa0


File system type (FSStat (1022   )):  PROC fs


fs_xia  =  $012FD16D


File system type (FSStat (1022   )):  XIA


F_GetFd  =  1


FCntl (1013   ) command:  Get close-on-exec flag



                                                                 950

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
F_GetFl  =  3


FCntl (1013   ) command:  Get filedescriptor flags


F_GetLk  =  5


FCntl (1013   ) command:  Get lock


F_GetOwn  =  9


FCntl (1013   ) command:  get owner of filedescriptor events


F_OK  =  0


Access (993  ) call test:  file exists.


F_SetFd  =  2


FCntl (1013   ) command:  Set close-on-exec flag


F_SetFl  =  4


FCntl (1013   ) command:  Set filedescriptor flags


F_SetLk  =  6


FCntl (1013   ) command:  Set lock


F_SetLkW  =  7


FCntl (1013   ) command:  Test lock


F_SetOwn  =  8


FCntl (1013   ) command:  Set owner of filedescriptor events


HUPCL  =  $0000400
ICANON  =  $0000002
ICRNL  =  $0000100
IEXTEN  =  $0008000
IGNBRK  =  $0000001
IGNCR  =  $0000080



                                                                 951

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
IGNPAR  =  $0000004
IMAXBEL  =  $0002000
INLCR  =  $0000040
INPCK  =  $0000010
IOCtl_TCGETS  =  $5401


IOCTL call number:  get Terminal Control settings


ISIG  =  $0000001
ISTRIP  =  $0000020
IUCLC  =  $0000200
IXANY  =  $0000800
IXOFF  =  $0001000
IXON  =  $0000400
LOCK_EX  =  2


FLock (1019   ) Exclusive lock


LOCK_NB  =  4


FLock (1019   ) Non-blocking operation


LOCK_SH  =  1


FLock (1019   ) Shared lock


LOCK_UN  =  8


FLock (1019   ) unlock


MAP_ANONYMOUS  =  $20


MMap (1040   ) map type:  Don't use a file



                                                                 952

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
MAP_DENYWRITE  =  $800


MMap (1040   ) option:  Ignored.


MAP_EXECUTABLE  =  $1000


MMap (1040   ) option:  Ignored.


MAP_FIXED  =  $10


MMap (1040   ) map type:  Interpret addr exactly


MAP_GROWSDOWN  =  $100


MMap (1040   ) option:  Memory grows downward (like a stack)


MAP_LOCKED  =  $2000


MMap (1040   ) option:  lock the pages in memory.


MAP_NORESERVE  =  $4000


MMap (1040   ) option:  Do not reserve swap pages for this memory.


MAP_PRIVATE  =  2


MMap (1040   ) map type:  Changes are private


MAP_SHARED  =  $1


MMap (1040   ) map type:  Share changes


MAP_TYPE  =  $f


MMap (1040   ) map type:  Bitmask for type of mapping


MINSIGSTKSZ  =  2048
NCC  =  8


Number of control characters in termio (989  ) record.


NCCS  =  32


Number of control characters in termios (990  ) record.


NL0  =  $0000000
NL1  =  $0000100



                                                                 953

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
NLDLY  =  $0000100
NOFLSH  =  $0000080
OCRNL  =  $0000008
OFDEL  =  $0000080
OFILL  =  $0000040
OLCUC  =  $0000002
ONLCR  =  $0000004
ONLRET  =  $0000020
ONOCR  =  $0000010
Open_Accmode  =  3


Bitmask to determine access mode in open flags.


Open_Append  =  2  shl  9


File open mode:  Append to file


Open_Creat  =  1  shl  6


File open mode:  Create if file does not yet exist.


Open_Direct  =  4  shl  12


File open mode:  Minimize caching effects


Open_Directory  =  2  shl  15


File open mode:  File must be directory.


Open_Excl  =  2  shl  6


File open mode:  Open exclusively


Open_LargeFile  =  1  shl  15



                                                                 954

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
File open mode:  Open for 64-bit I/O


Open_NDelay  =  Open_NonBlock


File open mode:  Alias for Open_NonBlock (955  )


Open_NoCtty  =  4  shl  6


File open mode:  No TTY control.


Open_NoFollow  =  4  shl  15


File open mode:  Fail if file is symbolic link.


Open_NonBlock  =  4  shl  9


File open mode:  Open in non-blocking mode


Open_RdOnly  =  0


File open mode:  Read only


Open_RdWr  =  2


File open mode:  Read/Write


Open_Sync  =  1  shl  12


File open mode:  Write to disc at once


Open_Trunc  =  1  shl  9


File open mode:  Truncate file to length 0


Open_WrOnly  =  1


File open mode:  Write only


OPOST  =  $0000001
PARENB  =  $0000100
PARMRK  =  $0000008
PARODD  =  $0000200
PENDIN  =  $0004000
                                                                 955

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Prio_PGrp  =  1


Get/set process group priority


Prio_Process  =  0


Get/Set process priority


Prio_User  =  2


Get/set user priority


PROT_EXEC  =  $4


MMap (1040   ) memory access:  page can be executed


PROT_NONE  =  $0


MMap (1040   ) memory access:  page can not be accessed


PROT_READ  =  $1


MMap (1040   ) memory access:  page can be read


PROT_WRITE  =  $2


MMap (1040   ) memory access:  page can be written


P_IN  =  1


Input file descriptor of pipe pair.


P_OUT  =  2


Output file descriptor of pipe pair.


R_OK  =  4


Access (993  ) call test:  read allowed


SA_INTERRUPT  =  $20000000


Sigaction options:  ?


SA_NOCLDSTOP  =  1


Sigaction options:  Do not receive notification when child processes stop


SA_NOMASK  =  $40000000


Sigaction options:  Do not prevent the signal from being received when it is handled.



                                                                 956

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
SA_ONESHOT  =  $80000000


Sigaction options:  Restore the signal action to the default state.


SA_ONSTACK  =  SA_STACK


Socket option


SA_RESTART  =  $10000000


Sigaction options:  Provide behaviour compatible with BSD signal semantics


SA_SHIRQ  =  $04000000


Sigaction options:  ?


SA_STACK  =  $08000000


Sigaction options:  Call the signal handler on an alternate signal stack.


Seek_Cur  =  1


Seek option:  Set position relative to current position.


Seek_End  =  2


Seek option:  Set position relative to end of file.


Seek_set  =  0


Seek option:  Set absolute position.


SIGABRT  =  6


Signal:  ABRT (Abort)


SIGALRM  =  14


Signal:  ALRM (Alarm clock)


SIGBUS  =  7


Signal:  BUS (bus error)


SIGCHLD  =  17


Signal:  CHLD (child status changed)


SIGCONT  =  18


Signal:  CONT (Continue)



                                                                 957

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
SIGFPE  =  8


Signal:  FPE (Floating point error)


SIGHUP  =  1


Signal:  HUP (Hangup)


SIGILL  =  4


Signal:  ILL (Illegal instruction)


SIGINT  =  2


Signal:  INT (Interrupt)


SIGIO  =  29


Signal:  IO (I/O operation possible)


SIGIOT  =  6


Signal:  IOT (IOT trap)


SIGKILL  =  9


Signal:  KILL (unblockable)


SIGPIPE  =  13


Signal:  PIPE (Broken pipe


SIGPOLL  =  SIGIO


Signal:  POLL (Pollable event)


SIGPROF  =  27


Signal:  PROF (Profiling alarm)


SIGPWR  =  30


Signal:  PWR (power failure restart)


SIGQUIT  =  3


Signal:  QUIT


SIGSEGV  =  11


Signal:  SEGV (Segmentation violation)



                                                                 958

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
SIGSTKFLT  =  16


Signal:  STKFLT (Stack Fault)


SIGSTKSZ  =  8192


Signal Stack size error


SIGSTOP  =  19


Signal:  STOP (Stop, unblockable)


SIGTerm  =  15


Signal:  TERM (Terminate)


SIGTRAP  =  5


Signal:  TRAP (Trace trap)


SIGTSTP  =  20


Signal:  TSTP (keyboard stop)


SIGTTIN  =  21


Signal:  TTIN (Terminal input, background)


SIGTTOU  =  22


Signal:  TTOU (Terminal output, background)


SIGUNUSED  =  31


Signal:  Unused


SIGURG  =  23


Signal:  URG (Socket urgent condition)


SIGUSR1  =  10


Signal:  USR1 (User-defined signal 1)


SIGUSR2  =  12


Signal:  USR2 (User-defined signal 2)


SIGVTALRM  =  26


Signal:  VTALRM (Virtual alarm clock)



                                                                 959

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
SIGWINCH  =  28


Signal:  WINCH (Window/Terminal size change)


SIGXCPU  =  24


Signal:  XCPU (CPU limit exceeded)


SIGXFSZ  =  25


Signal:  XFSZ (File size limit exceeded)


SIG_BLOCK  =  0


Sigprocmask flags:  Add signals to the set of blocked signals.


SIG_DFL  =  0


Signal handler:  Default signal handler


SIG_ERR  =  -1


Signal handler:  error


SIG_IGN  =  1


Signal handler:  Ignore signal


SIG_SETMASK  =  2


Sigprocmask flags:  Set of blocked signals is given.


SIG_UNBLOCK  =  1


Sigprocmask flags:  Remove signals from the set set of blocked signals.


SI_PAD_SIZE  =  (  (  128  /  sizeof  (  longint  )  )  -  3  )


Signal information record pad bytes size.  Do not use.


SS_DISABLE  =  2


Socket options


SS_ONSTACK  =  1


Socket options


STAT_IFBLK  =  $6000


File (stat (988  ) record) mode:  Block device



                                                                 960

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
STAT_IFCHR  =  $2000


File (stat (988  ) record) mode:  Character device


STAT_IFDIR  =  $4000


File (stat (988  ) record) mode:  Directory


STAT_IFIFO  =  $1000


File (stat (988  ) record) mode:  FIFO


STAT_IFLNK  =  $a000


File (stat (988  ) record) mode:  Link


STAT_IFMT  =  $f000


File (stat (988  ) record) mode:  File type bit mask


STAT_IFREG  =  $8000


File (stat (988  ) record) mode:  Regular file


STAT_IFSOCK  =  $c000


File (stat (988  ) record) mode:  Socket


STAT_IRGRP  =  STAT_IROTH  shl  3


File (stat (988  ) record) mode:  Group read permission


STAT_IROTH  =  $4


File (stat (988  ) record) mode:  Other read permission


STAT_IRUSR  =  STAT_IROTH  shl  6


File (stat (988  ) record) mode:  Owner read permission


STAT_IRWXG  =  STAT_IRWXO  shl  3


File (stat (988  ) record) mode:  Group permission bits mask


STAT_IRWXO  =  $7


File (stat (988  ) record) mode:  Other permission bits mask


STAT_IRWXU  =  STAT_IRWXO  shl  6


File (stat (988  ) record) mode:  Owner permission bits mask



                                                                 961

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
STAT_ISGID  =  $0400


File (stat (988  ) record) mode:  GID bit set


STAT_ISUID  =  $0800


File (stat (988  ) record) mode:  UID bit set


STAT_ISVTX  =  $0200


File (stat (988  ) record) mode:  Sticky bit set


STAT_IWGRP  =  STAT_IWOTH  shl  3


File (stat (988  ) record) mode:  Group write permission


STAT_IWOTH  =  $2


File (stat (988  ) record) mode:  Other write permission


STAT_IWUSR  =  STAT_IWOTH  shl  6


File (stat (988  ) record) mode:  Owner write permission


STAT_IXGRP  =  STAT_IXOTH  shl  3


File (stat (988  ) record) mode:  Others execute permission


STAT_IXOTH  =  $1


File (stat (988  ) record) mode:  Others execute permission


STAT_IXUSR  =  STAT_IXOTH  shl  6


File (stat (988  ) record) mode:  Others execute permission


syscall_nr_access  =  33
syscall_nr_acct  =  51
syscall_nr_adjtimex  =  124
syscall_nr_afs_syscall  =  137
syscall_nr_alarm  =  27
syscall_nr_bdflush  =  134



                                                                 962

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_break  =  17
syscall_nr_brk  =  45
syscall_nr_chdir  =  12
syscall_nr_chmod  =  15
syscall_nr_chown  =  16
syscall_nr_chroot  =  61
syscall_nr_clone  =  120
syscall_nr_close  =  6
syscall_nr_creat  =  8
syscall_nr_create_module  =  127
syscall_nr_delete_module  =  129
syscall_nr_dup  =  41
syscall_nr_dup2  =  63
syscall_nr_execve  =  11
syscall_nr_exit  =  1
syscall_nr_fchdir  =  133
syscall_nr_fchmod  =  94
syscall_nr_fchown  =  95
syscall_nr_fcntl  =  55

                                                                 963

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_fdatasync  =  148
syscall_nr_flock  =  143
syscall_nr_fork  =  2
syscall_nr_fstat  =  108
syscall_nr_fstatfs  =  100
syscall_nr_fsync  =  118
syscall_nr_ftime  =  35
syscall_nr_ftruncate  =  93
syscall_nr_getdents  =  141
syscall_nr_getegid  =  50
syscall_nr_geteuid  =  49
syscall_nr_getgid  =  47
syscall_nr_getgroups  =  80
syscall_nr_getitimer  =  105
syscall_nr_getpgid  =  132
syscall_nr_getpgrp  =  65
syscall_nr_getpid  =  20
syscall_nr_getppid  =  64
syscall_nr_getpriority  =  96

                                                                 964

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_getresuid  =  165
syscall_nr_getrlimit  =  76
syscall_nr_getrusage  =  77
syscall_nr_getsid  =  147
syscall_nr_gettimeofday  =  78
syscall_nr_getuid  =  24
syscall_nr_get_kernel_syms  =  130
syscall_nr_gtty  =  32
syscall_nr_idle  =  112
syscall_nr_init_module  =  128
syscall_nr_ioctl  =  54
syscall_nr_ioperm  =  101
syscall_nr_iopl  =  110
syscall_nr_ipc  =  117
syscall_nr_kill  =  37
syscall_nr_link  =  9
syscall_nr_lock  =  53
syscall_nr_lseek  =  19
syscall_nr_lstat  =  107

                                                                 965

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_mkdir  =  39
syscall_nr_mknod  =  14
syscall_nr_mlock  =  150
syscall_nr_mlockall  =  152
syscall_nr_mmap  =  90
syscall_nr_modify_ldt  =  123
syscall_nr_mount  =  21
syscall_nr_mprotect  =  125
syscall_nr_mpx  =  56
syscall_nr_mremap  =  163
syscall_nr_msync  =  144
syscall_nr_munlock  =  151
syscall_nr_munlockall  =  153
syscall_nr_munmap  =  91
syscall_nr_nanosleep  =  162
syscall_nr_nice  =  34
syscall_nr_oldfstat  =  28
syscall_nr_oldlstat  =  84
syscall_nr_oldolduname  =  59

                                                                 966

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_oldstat  =  18
syscall_nr_olduname  =  109
syscall_nr_open  =  5
syscall_nr_pause  =  29
syscall_nr_personality  =  136
syscall_nr_phys  =  52
syscall_nr_pipe  =  42
syscall_nr_poll  =  168
syscall_nr_prof  =  44
syscall_nr_profil  =  98
syscall_nr_ptrace  =  26
syscall_nr_query_module  =  167
syscall_nr_quotactl  =  131
syscall_nr_read  =  3
syscall_nr_readdir  =  89
syscall_nr_readlink  =  85
syscall_nr_readv  =  145
syscall_nr_reboot  =  88
syscall_nr_rename  =  38

                                                                 967

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_rmdir  =  40
syscall_nr_sched_getparam  =  155
syscall_nr_sched_getscheduler  =  157
syscall_nr_sched_get_priority_max  =  159
syscall_nr_sched_get_priority_min  =  160
syscall_nr_sched_rr_get_interval  =  161
syscall_nr_sched_setparam  =  154
syscall_nr_sched_setscheduler  =  156
syscall_nr_sched_yield  =  158
syscall_nr_select  =  82
syscall_nr_setdomainname  =  121
syscall_nr_setfsgid  =  139
syscall_nr_setfsuid  =  138
syscall_nr_setgid  =  46
syscall_nr_setgroups  =  81
syscall_nr_sethostname  =  74
syscall_nr_setitimer  =  104
syscall_nr_setpgid  =  57
syscall_nr_setpriority  =  97

                                                                 968

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_setregid  =  71
syscall_nr_setresuid  =  164
syscall_nr_setreuid  =  70
syscall_nr_setrlimit  =  75
syscall_nr_setsid  =  66
syscall_nr_settimeofday  =  79
syscall_nr_setuid  =  23
syscall_nr_setup  =  0
syscall_nr_sgetmask  =  68
syscall_nr_sigaction  =  67
syscall_nr_sigaltstack  =  186
syscall_nr_signal  =  48
syscall_nr_sigpending  =  73
syscall_nr_sigprocmask  =  126
syscall_nr_sigreturn  =  119
syscall_nr_sigsuspend  =  72
syscall_nr_socketcall  =  102
syscall_nr_ssetmask  =  69
syscall_nr_stat  =  106

                                                                 969

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_statfs  =  99
syscall_nr_stime  =  25
syscall_nr_stty  =  31
syscall_nr_swapoff  =  115
syscall_nr_swapon  =  87
syscall_nr_symlink  =  83
syscall_nr_sync  =  36
syscall_nr_sysfs  =  135
syscall_nr_sysinfo  =  116
syscall_nr_syslog  =  103
syscall_nr_time  =  13
syscall_nr_times  =  43
syscall_nr_truncate  =  92
syscall_nr_ulimit  =  58
syscall_nr_umask  =  60
syscall_nr_umount  =  22
syscall_nr_uname  =  122
syscall_nr_unlink  =  10
syscall_nr_uselib  =  86

                                                                 970

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
syscall_nr_ustat  =  62
syscall_nr_utime  =  30
syscall_nr_vhangup  =  111
syscall_nr_vm86  =  166
syscall_nr_vm86old  =  113
syscall_nr_wait4  =  114
syscall_nr_waitpid  =  7
syscall_nr_write  =  4
syscall_nr_writev  =  146
syscall_nr__llseek  =  140
syscall_nr__newselect  =  142
syscall_nr__sysctl  =  149
Sys_E2BIG  =  7
Sys_EACCES  =  13
Sys_EADDRINUSE  =  98
Sys_EADDRNOTAVAIL  =  99
Sys_EADV  =  68
Sys_EAFNOSUPPORT  =  97
Sys_EAGAIN  =  11

                                                                 971

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_EALREADY  =  114
Sys_EBADE  =  52
Sys_EBADF  =  9
Sys_EBADFD  =  77
Sys_EBADMSG  =  74
Sys_EBADR  =  53
Sys_EBADRQC  =  56
Sys_EBADSLT  =  57
Sys_EBFONT  =  59
Sys_EBUSY  =  16
Sys_ECHILD  =  10
Sys_ECHRNG  =  44
Sys_ECOMM  =  70
Sys_ECONNABORTED  =  103
Sys_ECONNREFUSED  =  111
Sys_ECONNRESET  =  104
Sys_EDEADLK  =  35
Sys_EDEADLOCK  =  58
Sys_EDESTADDRREQ  =  89

                                                                 972

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_EDOM  =  33
Sys_EDOTDOT  =  73
Sys_EDQUOT  =  122
Sys_EEXIST  =  17
Sys_EFAULT  =  14
Sys_EFBIG  =  27
Sys_EHOSTDOWN  =  112
Sys_EHOSTUNREACH  =  113
Sys_EIDRM  =  43
Sys_EILSEQ  =  84
Sys_EINPROGRESS  =  115
Sys_EINTR  =  4
Sys_EINVAL  =  22
Sys_EIO  =  5
Sys_EISCONN  =  106
Sys_EISDIR  =  21
Sys_EISNAM  =  120
Sys_EL2HLT  =  51
Sys_EL2NSYNC  =  45

                                                                 973

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_EL3HLT  =  46
Sys_EL3RST  =  47
Sys_ELIBACC  =  79
Sys_ELIBBAD  =  80
Sys_ELIBEXEC  =  83
Sys_ELIBMAX  =  82
Sys_ELIBSCN  =  81
Sys_ELNRNG  =  48
Sys_ELOOP  =  40
Sys_EMFILE  =  24
Sys_EMLINK  =  31
Sys_EMSGSIZE  =  90
Sys_EMULTIHOP  =  72
Sys_ENAMETOOLONG  =  36
Sys_ENAVAIL  =  119
Sys_ENETDOWN  =  100
Sys_ENETRESET  =  102
Sys_ENETUNREACH  =  101
Sys_ENFILE  =  23

                                                                 974

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_ENOANO  =  55
Sys_ENOBUFS  =  105
Sys_ENOCSI  =  50
Sys_ENODATA  =  61
Sys_ENODEV  =  19
Sys_ENOENT  =  2
Sys_ENOEXEC  =  8
Sys_ENOLCK  =  37
Sys_ENOLINK  =  67
Sys_ENOMEM  =  12
Sys_ENOMSG  =  42
Sys_ENONET  =  64
Sys_ENOPKG  =  65
Sys_ENOPROTOOPT  =  92
Sys_ENOSPC  =  28
Sys_ENOSR  =  63
Sys_ENOSTR  =  60
Sys_ENOSYS  =  38
Sys_ENOTBLK  =  15

                                                                 975

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_ENOTCONN  =  107
Sys_ENOTDIR  =  20
Sys_ENOTEMPTY  =  39
Sys_ENOTNAM  =  118
Sys_ENOTSOCK  =  88
Sys_ENOTTY  =  25
Sys_ENOTUNIQ  =  76
Sys_ENXIO  =  6
Sys_EOPNOTSUPP  =  95
Sys_EOVERFLOW  =  75
Sys_EPERM  =  1
Sys_EPFNOSUPPORT  =  96
Sys_EPIPE  =  32
Sys_EPROTO  =  71
Sys_EPROTONOSUPPORT  =  93
Sys_EPROTOTYPE  =  91
Sys_ERANGE  =  34
Sys_EREMCHG  =  78
Sys_EREMOTE  =  66

                                                                 976

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_EREMOTEIO  =  121
Sys_ERESTART  =  85
Sys_EROFS  =  30
Sys_ERROR_MAX  =  $fff
Sys_ESHUTDOWN  =  108
Sys_ESOCKTNOSUPPORT  =  94
Sys_ESPIPE  =  29
Sys_ESRCH  =  3
Sys_ESRMNT  =  69
Sys_ESTALE  =  116
Sys_ESTRPIPE  =  86
Sys_ETIME  =  62
Sys_ETIMEDOUT  =  110
Sys_ETOOMANYREFS  =  109
Sys_ETXTBSY  =  26
Sys_EUCLEAN  =  117
Sys_EUNATCH  =  49
Sys_EUSERS  =  87
Sys_EWOULDBLOCK  =  Sys_EAGAIN

                                                                 977

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Sys_EXDEV  =  18
Sys_EXFULL  =  54
TAB0  =  $0000000
TAB1  =  $0000800
TAB2  =  $0001000
TAB3  =  $0001800
TABDLY  =  $0001800
TCFLSH  =  $540B
TCGETA  =  $5405
TCGETS  =  $5401
TCIFLUSH  =  0
TCIOFF  =  2
TCIOFLUSH  =  2
TCION  =  3
TCOFLUSH  =  1
TCOOFF  =  0
TCOON  =  1
TCSADRAIN  =  1
TCSAFLUSH  =  2
                                                                 978

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
TCSANOW  =  0
TCSBRK  =  $5409
TCSBRKP  =  $5425
TCSETA  =  $5406
TCSETAF  =  $5408
TCSETAW  =  $5407
TCSETS  =  $5402
TCSETSF  =  $5404
TCSETSW  =  $5403
TCXONC  =  $540A
TIOCCONS  =  $541D
TIOCEXCL  =  $540C
TIOCGETD  =  $5424
TIOCGICOUNT  =  $545D
TIOCGLCKTRMIOS  =  $5456
TIOCGPGRP  =  $540F
TIOCGSERIAL  =  $541E
TIOCGSOFTCAR  =  $5419
TIOCGWINSZ  =  $5413
                                                                 979

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
TIOCINQ  =  FIONREAD
TIOCLINUX  =  $541C
TIOCMBIC  =  $5417
TIOCMBIS  =  $5416
TIOCMGET  =  $5415
TIOCMIWAIT  =  $545C
TIOCMSET  =  $5418
TIOCM_CAR  =  $040
TIOCM_CD  =  TIOCM_CAR
TIOCM_CTS  =  $020
TIOCM_DSR  =  $100
TIOCM_DTR  =  $002
TIOCM_LE  =  $001
TIOCM_OUT1  =  $2000
TIOCM_OUT2  =  $4000
TIOCM_RI  =  TIOCM_RNG
TIOCM_RNG  =  $080
TIOCM_RTS  =  $004
TIOCM_SR  =  $010
                                                                 980

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
TIOCM_ST  =  $008
TIOCNOTTY  =  $5422
TIOCNXCL  =  $540D
TIOCOUTQ  =  $5411
TIOCPKT  =  $5420
TIOCPKT_DATA  =  0
TIOCPKT_DOSTOP  =  32
TIOCPKT_FLUSHREAD  =  1
TIOCPKT_FLUSHWRITE  =  2
TIOCPKT_NOSTOP  =  16
TIOCPKT_START  =  8
TIOCPKT_STOP  =  4
TIOCSCTTY  =  $540E
TIOCSERCONFIG  =  $5453
TIOCSERGETLSR  =  $5459
TIOCSERGETMULTI  =  $545A
TIOCSERGSTRUCT  =  $5458
TIOCSERGWILD  =  $5454
TIOCSERSETMULTI  =  $545B
                                                                 981

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
TIOCSERSWILD  =  $5455
TIOCSETD  =  $5423
TIOCSLCKTRMIOS  =  $5457
TIOCSPGRP  =  $5410
TIOCSSERIAL  =  $541F
TIOCSSOFTCAR  =  $541A
TIOCSTI  =  $5412
TIOCSWINSZ  =  $5414
TIOCTTYGSTRUCT  =  $5426
TOSTOP  =  $0000100
VDISCARD  =  13
VEOF  =  4
VEOL  =  11
VEOL2  =  16
VERASE  =  2
VINTR  =  0
VKILL  =  3
VLNEXT  =  15
VMIN  =  6
                                                                 982

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
VQUIT  =  1
VREPRINT  =  12
VSTART  =  8
VSTOP  =  9
VSUSP  =  10
VSWTC  =  7
VT0  =  $0000000
VT1  =  $0004000
VTDLY  =  $0004000
VTIME  =  5
VWERASE  =  14
Wait_Any  =  -1


WaitPID (1068   ):  Wait on any process


Wait_Clone  =  $80000000


WaitPID (1068   ):  Wait on clone processes only.


Wait_MyPGRP  =  0


WaitPID (1068   ):  Wait processes from current process group


Wait_NoHang  =  1


WaitPID (1068   ):  Do not wait


Wait_UnTraced  =  2


WaitPID (1068   ):  Also report stopped but untraced processes


WNOHANG  =  $1



                                                                 983

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Waitpid (1068   ) option:  Do not wait for processes to terminate.


WUNTRACED  =  $2


Waitpid (1068   ) option:  Also report children wich were stopped but not yet reported


W_OK  =  2


Access (993  ) call test:  write allowed


XCASE  =  $0000004
XTABS  =  $0001800
X_OK  =  1


Access (993  ) call test:  execute allowed


__WCLONE  =  $80000000


Waitpid option:  Wait for clone children only
23.11.2          Types

ComStr  =


Command-line string type.


dev_t  =  Word


Device descriptor type


dirent  =  packed  record
    ino  :  LongInt;
    off  :  LongInt;
    reclen  :  Word;
    name  :  Array[0..255]  of  Char;
end
Record used in the ReadDir (1046   ) function to return files in a directory.


DirStr  =


Filename directory part string type.


ExtStr  =


Filename extension part string type.



                                                                 984

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
fdSet  =  Array[0..7]  of  LongInt


Array containing file descriptor bitmask for the Select (1048   ) call.


NameStr  =


Filename name part string type.


PathStr  =


Filename path part string type.


PDir  =  ^TDir


Pointer to TDir (989  ) record


pdirent  =  ^dirent


Pointer to Dirent (984  ) record.


pfdset  =  ^fdSet


Pointer to FDSet (1018   ) array.


pfpstate  =  ^tfpstate


Pointer to tfpstate (990  ) record.


pglob  =  ^tglob


Pointer to TGlob (990  ) record.


PSigActionRec  =  ^SigActionRec


Pointer to SigActionRec (986  ) record.


PSigAltStack  =  ^SigAltStack


Pointer to SigAltStack (987  ) record


PSigContextRec  =  ^SigContextRec


Pointer to SigContextRec (987  ) record


PSignalHandler  =  ^SignalHandler


Pointer to SignalHandler (987  ) type.


PSignalRestorer  =  ^SignalRestorer


Pointer to SignalRestorer (987  ) type



                                                                 985

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
PSigSet  =  ^SigSet


Pointer to signal set.


pstack_t  =  ^stack_t


Pointer to stack_t (988  ) record


PStat  =  ^Stat


Pointer to Stat (988  ) record.


PStatFS  =  ^Statfs


Pointer to StatFS (988  ) record.


PSysCallRegs  =  ^SysCallRegs


Pointer to SysCallRegs (989  ) record.


PSysInfo  =  ^TSysinfo


Pointer to TSysInfo (992  ) record.


ptimeval  =  ^timeval


Pointer to TTimeVal (992  ) record


ptimezone  =  ^timezone


Pointer to TimeZone (991  ) record.


PUTimeBuf  =  ^UTimeBuf


Pointer to UTimeBuf (992  ) record


PUTSName  =  ^utsname


Pointer to UTSName (993  ) record.


SigActionRec  =  packed  record
   Handler  :  record
   end;
   Sa_Mask  :  SigSet;
   Sa_Flags  :  LongInt;
   Sa_restorer  :  SignalRestorer;
end
Record used in SigAction (1052   ) call.



                                                                 986

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
SigAltStack  =  record
   ss_sp  :  pointer;
   ss_flags  :  LongInt;
   ss_size  :  Size_T;
end
Alternate stack registers record


SigContextRec  =  record
   gs  :  Word;
   __gsh  :  Word;
   fs  :  Word;
   __fsh  :  Word;
   es  :  Word;
   __esh  :  Word;
   ds  :  Word;
   __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  :  Word;
   __csh  :  Word;
   eflags  :  cardinal;
   esp_at_signal  :  cardinal;
   ss  :  Word;
   __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.


SignalHandler  =  procedure(Sig:  LongInt)


Function prototype for the Signal (1053   ) call.


SignalRestorer  =  procedure


Signal restorer function prototype


SigSet  =  LongInt



                                                                 987

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Signal set type


Size_T  =  cardinal


Size type


stack_t  =  SigAltStack


Alias for SigAltStack (987  ) type


Stat  =  packed  record
   dev  :  dev_t;
   pad1  :  Word;
   ino  :  LongInt;
   mode  :  Word;
   nlink  :  Word;
   uid  :  Word;
   gid  :  Word;
   rdev  :  dev_t;
   pad2  :  Word;
   size  :  LongInt;
   blksize  :  LongInt;
   blocks  :  LongInt;
   atime  :  LongInt;
   unused1  :  LongInt;
   mtime  :  LongInt;
   unused2  :  LongInt;
   ctime  :  LongInt;
   unused3  :  LongInt;
   unused4  :  LongInt;
   unused5  :  LongInt;
end
Record describing an inode (file) in the fstat (1023   ) call.


Statfs  =  packed  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
Record describing a file system in the fsstat (1022   ) call.


                                                                 988

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
SysCallRegs  =  record
   reg1  :  LongInt;
   reg2  :  LongInt;
   reg3  :  LongInt;
   reg4  :  LongInt;
   reg5  :  LongInt;
   reg6  :  LongInt;
end
Register describing system calls.


TCloneFunc  =  function(args:  pointer)  :  LongInt


Clone function prototype.


TDir  =  packed  record
   fd  :  Integer;
   loc  :  LongInt;
   size  :  Integer;
   buf  :  pdirent;
   nextoff  :  LongInt;
   dd_max  :  Integer;
   lock  :  pointer;
end
Record used in OpenDir (1043   ) and ReadDir (1046   ) calls


TDirEnt  =  dirent


Alias for DirEnt (984  ) record


Termio  =  packed  record
   c_iflag  :  Word;
   c_oflag  :  Word;
   c_cflag  :  Word;
   c_lflag  :  Word;
   c_line  :  Word;
   c_cc  :  Array[0..NCC-1]  of  Char;
end
Terminal I/O description record (small)


Termios  =  record
   c_iflag  :  Cardinal;
   c_oflag  :  Cardinal;
   c_cflag  :  Cardinal;
   c_lflag  :  Cardinal;
   c_line  :  Char;
   c_cc  :  Array[0..NCCS-1]  of  Byte;



                                                                 989

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
   c_ispeed  :  LongInt;
   c_ospeed  :  LongInt;
end
Terminal I/O description record


TFDSet  =  fdSet


Alias for FDSet (1018   ) type.


tfpreg  =  record
   significand  :  Array[0..3]  of  Word;
   exponent  :  Word;
end
Record describing floating point register in signal handler.


tfpstate  =  record
   cw  :  cardinal;
   sw  :  cardinal;
   tag  :  cardinal;
   ipoff  :  cardinal;
   cssel  :  cardinal;
   dataoff  :  cardinal;
   datasel  :  cardinal;
   st  :  Array[0..7]  of  tfpreg;
   status  :  cardinal;
end
Record describing floating point unit in signal handler.


tglob  =  record
   name  :  pchar;
   next  :  pglob;
end
Record containing one entry in the result of Glob (1033   )


timespec  =  packed  record
   tv_sec  :  LongInt;
   tv_nsec  :  LongInt;
end
Time interval for the NanoSleep (1041   ) function.


timeval  =  packed  record
   sec  :  LongInt;
   usec  :  LongInt;
end

                                                                 990

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Record specifying a time inteval.


timezone  =  packed  record
   minuteswest  :  LongInt;
   dsttime  :  LongInt;
end
Record describing a timezone


tmmapargs  =  record
   address  :  LongInt;
   size  :  LongInt;
   prot  :  LongInt;
   flags  :  LongInt;
   fd  :  LongInt;
   offset  :  LongInt;
end
Record containing mmap args.


Tpipe  =  Array[1..2]  of  LongInt


Array describing a pipe pair of filedescriptors.


TSigAction  =  procedure(Sig:  LongInt;SigContext:  SigContextRec)


Function prototype for SigAction (1052   ) call.


TStat  =  Stat


Alias for Stat (988  ) record.


TStatFS  =  Statfs


Alias for StatFS (988  ) type.


TSysCallRegs  =  SysCallRegs


Alias for SysCallRegs (989  ) record


TSysinfo  =  packed  record
   uptime  :  LongInt;
   loads  :  Array[1..3]  of  LongInt;
   totalram  :  LongInt;
   freeram  :  LongInt;
   sharedram  :  LongInt;
   bufferram  :  LongInt;
   totalswap  :  LongInt;
   freeswap  :  LongInt;
   procs  :  Integer;
   s  :  String;
end

                                                                 991

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
Record with system information, used by the SysInfo (1058   ) call.


TTermio  =  Termio


Alias for TermIO (989  ) record


TTermios  =  Termios


Alias for Termios (990  ) record.


TTimeVal  =  timeval


Alias for TimeVal (991  ) record.


TTimeZone  =  timezone


Alias for TimeZone (991  ) record.


TUTimeBuf  =  UTimeBuf


Alias for UTimBuf (992  ) record.


TUTSName  =  utsname


Alias for UTSName (993  ) record.


TWinSize  =  winsize


Alias for WinSize (993  ) record.


UTimBuf  =  packed  record
   actime  :  LongInt;
   modtime  :  LongInt;
end
Record used in Utime (1067   ) to set file access and modificaton times.


UTimeBuf  =  UTimBuf


Alias for UTimBuf (992  ) record.


utsname  =  packed  record
   sysname  :  Array[0..64]  of  Char;
   nodename  :  Array[0..64]  of  Char;
   release  :  Array[0..64]  of  Char;
   version  :  Array[0..64]  of  Char;
   machine  :  Array[0..64]  of  Char;
   domainname  :  Array[0..64]  of  Char;
end

                                                                 992

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                The  elements  of  this  record  are  null-terminated  C  style  strings,  you  cannot  access  them
                directly.


                winsize  =  packed  record
                   ws_row  :  Word;
                   ws_col  :  Word;
                   ws_xpixel  :  Word;
                   ws_ypixel  :  Word;
                end
                Record describing terminal window size.
                23.11.3          Variables

                ErrNo  :  LongInt


                Error number of last operation.


                LinuxError  :  LongInt


                Linuxerror is the variable in which the procedures in the linux unit report errors.


                tzdaylight  :  Boolean


                Indicates whether daylight savings time is active.


                tzname  :  Array[boolean]  of  pchar


                Timezone name.


                tzseconds  :  LongInt


                Seconds west of GMT
                23.12            Procedures  and  functions



                23.12.1          Access

    Synopsis:    Check file access

Declaration:     function  Access(Path:  PathStr;mode:  Integer)  :  Boolean

    Visibility:   default

Description:     Access tests user's access rights on the specified file.  Mode is a mask existing of one or more
                of the following:


                R__OK     User has read rights.

                W__OK      User has write rights.

                X__OK     User has execute rights.



                                                                                 993

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                F__OK    File exists.


                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.

                sys__enomem        Insufficient kernel memory.

                sys__eloop    Path has a circular symbolic link.


    See also:    Chown (1000   ), Chmod (999  )


                Listing:  ./olinuxex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   Program       t o  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     o l d l i n u x;


                 b e g i n
                    i f  A c c e s s (  '/ e t c/ p a s s w d',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  c a n   w r i t e t o  t h e  / e t c/ p a s s w d f i l e  ! ') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.2          Alarm

    Synopsis:    Schedule an alarm signal to be delivered

Declaration:     function  Alarm(Sec:  LongInt)  :  LongInt

    Visibility:   default

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.

    See also:    SigAction (1052   )


                Listing:  ./olinuxex/ex59.pp


                                                                                 994

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 9;


                {   Program       t o  d e m o n s t r a t et h e  Alarm      f u n c t i o n. }


                Uses     o l d l i n u x;


                 P r o c e d u r eA 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    t o   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 gAlarm     i n  1 0   s e c o n d s') ;
                    Alarm    ( 1 0 ) ;
                    W r i t e l n ( 'P a u s i n g' ) ;
                    P a u s e;
                    W r i t e l n ( 'P a u s e  r e t u r n e d') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.3          AssignPipe

    Synopsis:    Create a set of pipe file handlers

Declaration:     function  AssignPipe(var  pipe_in:  LongInt;var  pipe_out:  LongInt)
                                                 :  Boolean
                function  AssignPipe(var  pipe_in:  text;var  pipe_out:  text)  :  Boolean
                function  AssignPipe(var  pipe_in:  File;var  pipe_out:  File)  :  Boolean

    Visibility:   default

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 (1045   ), MkFifo (1039   )


                Listing:  ./olinuxex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n P i p ef u n c t i o n.  }


                Uses     o l d l i n u x;



                                                                                 995

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________


                Var     p i p i,p i p o  :  T e x t ;
                        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 gP i p e s. ') ;
                    I f  Not    a s s i g n p i p e(p 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 gp 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 gt o   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 f r o m  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     f r o m 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.4          AssignStream

    Synopsis:    Assign stream for in and output to a program

Declaration:     function  AssignStream(var  StreamIn:  text;var  Streamout:  text;
                                                   const  Prog:  String)  :  LongInt
                function  AssignStream(var  StreamIn:  Text;var  StreamOut:  Text;
                                                   var  StreamErr:  Text;const  prog:  String)  :  LongInt

    Visibility:   default

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
                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 (995  ), POpen (1045   )


                Listing:  ./olinuxex/ex38.pp



                                                                                 996

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   Program       t o  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     o l d l i n u x;


                Var     S i, So   :  T e x t ;
                       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)=  '- s o n ' )  then
                        b e g i n
                        W r i t e l n(  'C a l l i n g s o n' ) ;
                        A s s i g n s t r e a m(S i ,So  , '. / e x 3 8-  s o n ') ;
                        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 mf 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 t o  s o n' ) ;
                       For     i: = 1  t o  1 0  do
                           b e g i n
                           w r i t e l n ( so , ' H e l l o s o n  ! ' ) ;
                           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 t o  s o n . . .' ) ;
                           end  ;
                       For     i: = 1  t o  3   do   w r i t e l n ( so , ' H e l l o c h a p  ! ' ) ;
                        c l o s e ( s o) ;
                        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) ;
                        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  s o n  ' ) ;
                       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 s o n  ! ' ,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___.____________________________________________________________________________________________________________*
 *___________

                23.12.5          Basename

    Synopsis:    Return basename of a file

Declaration:     function  Basename(const  path:  PathStr;const  suf:  PathStr)  :  PathStr



                                                                                 997

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    Visibility:  default

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 (1004   ), FExpand (1018   )


                Listing:  ./olinuxex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   Program       t o  d e m o n s t r a t et h e  BaseName        f u n c t i o n. }


                Uses     o l d 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 p r o g r a m i s   c a l l e d :  ' ,Basename      ( S , ' ') ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.6          CFMakeRaw

    Synopsis:    Sets flags in Termios (990  ) record.

Declaration:     procedure  CFMakeRaw(var  tios:  Termios)

    Visibility:   default

Description:     CFMakeRaw sets the flags in the Termios structure Tios to a state so that the terminal will
                function in Raw Mode.

                For an example, see TCGetAttr (1063   ).

       Errors:   None.

    See also:    CFSetOSpeed (999  ), CFSetISpeed (998  )
                23.12.7          CFSetISpeed

    Synopsis:    Set input baud rate in Termios (990  ) record

Declaration:     procedure  CFSetISpeed(var  tios:  Termios;speed:  Cardinal)

    Visibility:   default

Description:     CFSetISpeed Sets the input baudrate in the TermIOS structure Tios to Speed.

       Errors:   None.

    See also:    CFSetOSpeed (999  ), CFMakeRaw (998  )

                                                                                 998

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.8          CFSetOSpeed

    Synopsis:    Set output baud rate in Termios (990  ) record

Declaration:     procedure  CFSetOSpeed(var  tios:  Termios;speed:  Cardinal)

    Visibility:   default

Description:     CFSetOSpeed Sets the output baudrate in the Termios structure Tios to Speed.

       Errors:   None.

    See also:    CFSetISpeed (998  ), CFMakeRaw (998  )
                23.12.9          Chmod

    Synopsis:    Change file permission bits

Declaration:     function  Chmod(path:  PathStr;Newmode:  LongInt)  :  Boolean

    Visibility:   default

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__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.



                                                                                 999

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    See also:    Chown (1000   ), Access (993  ), Octal (1043   )


                Listing:  ./olinuxex/ex23.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 3;


                {   Program       t o  d e m o n s t r a t et h e  Chmod      f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    F   :  T e x t ;


                 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/ s h ' ) ;
                    W r i t e l n ( f , 'e c h o 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      f r o m  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___.____________________________________________________________________________________________________________*
 *___________

                23.12.10           Chown

    Synopsis:    Change owner of file

Declaration:     function  Chown(path:  PathStr;NewUid:  LongInt;NewGid:  LongInt)  :  Boolean

    Visibility:   default

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__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 (999  ), Access (993  )


                Listing:  ./olinuxex/ex24.pp



                                                                                1000

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 4;


                {   Program       t o  d e m o n s t r a t et h e  Chown      f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    UID   ,GID     :  L o n g i n t;
                       F   :  T e x t ;


                 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. ') ;
                    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  n o t  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  c o d e :   ' ,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___.____________________________________________________________________________________________________________*
 *___________

                23.12.11           Clone

    Synopsis:    Clone current process (create new thread)

Declaration:     function  Clone(func:  TCloneFunc;sp:  pointer;flags:  LongInt;
                                       args:  pointer)  :  LongInt

    Visibility:   default

Description:     Clone creates a child process which is a copy of the parent process,  just like Fork (1020   )
                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.



                                                                                1001

            ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'______________________*
 *_______________
            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.

            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 (1020   )


            Listing:  ./olinuxex/ex71.pp
            _______________________________________________________________________________________________________________________*
 *_______
            program       TestC    { l o n e} ;


             u s e s
                o l d l i n u x,  E r r o r s,  c r t;


             c o n s t
                Ready      :  B o o l e a n=    f a l s e;
                a C h a r  :  Char          =   'a ' ;


             f u n c t i o nC l o n e P r o c( Arg   :  P o i n t e r ) :  L o n g I n t;  C d e c l;
             b e g i n
                WriteLn     ( ' H e l l o f r o m  t h e  c l o n e  ', PChar    (Arg   ) ) ;
                r e p e a t
                   Write    ( a C h a r) ;
                    S e l e c t( 0 ,N i l,N i l ,N i l ,N i l ) ;
                u n t i l Ready    ;
                WriteLn     (   'C l o n e  f i n i s h e d.' ) ;
                C l o n e P r o c: =  1 ;
            end   ;


             v a r
                PID    :   L o n g I n t;


             p r o c e d u r eMainProc      ;
             b e g i n
                WriteLn     ( ' c l o n e d p r o c e s s PID  :   ' ,  PID    ) ;
                WriteLn     ( ' P r e s s<  ESC  >   t o  k i l l  . . .  '  ) ;
                r e p e a t
                   Write    ( ' . ') ;
                    S e l e c t( 0 ,N i l,N i l ,N i l ,N i l ) ;
                    i f  KeyPressed         then
                       c a s e  ReadKey       o f
                          # 2 7 :  Ready     : =   t r u e;
                           'a ' :  a C h a r : =   'A  ';
                           'A ' :  a C h a r : =   ' a ';
                           'b ' :  a C h a r : =   'b  ';
                           'B ' :  a C h a r : =   'B  ';
                       end  ;
                u n t i l Ready    ;
                WriteLn     ( ' Ready    . ') ;
            end   ;
                                                                            1002

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                 c o n s t
                    S t a c k S z e=  1 6 3 8 4 ;
                    t h e F l a g s=   CLONE_VM      + CLONE_FS     + CLONE _FILES       + CLONE_SIGHAND          ;
                    aMsg            :  PChar     =   ' Oops     ! ';


                 v a r
                    t h e S t a c k :  P o i n t e r;
                    E x i t S t a t :  L o n g I n t;


                 b e g i n
                    GetMem    ( t h e S t a c k,S t a c k S z e) ;
                    PID    : =  C l o n e( @ C l o n e P r o,c
                                           P o i n t e r( L o n g I n t(t h e S t a c k)+ S t a c k S z e) ,
                                           t h e F l a g s,
                                          aMsg    ) ;
                    i f  PID    <  0   then
                       WriteLn      ( 'E r r o r  :  ' ,  L i n u x E r r o r,  '  when     c l o n i n g.')
                    e l s e
                        b e g i n
                       MainProc       ;
                        c a s e WaitPID      ( 0 ,@ E x i t S t a t,W a i t _U n t r a c e do r  w a i t _c l o n e)  o f
                           -1:    WriteLn     ( ' e r r o r:' , L i n u x E r r o,r' ;  ' , S t r E r r o(rL i n u x E r r o r) ) ;
                             0 :  WriteLn     ( ' e r r o r:' , L i n u x E r r o,r' ;  ' , S t r E r r o(rL i n u x E r r o r) ) ;
                        e l s e
                           WriteLn     ( ' C l o n e e x i t e d w i t h :  ' ,E x i t S t a t s h r  8 ) ;
                       end   ;
                       end   ;
                    FreeMem     (   t h e S t a c k, S t a c k S z e ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.12           CloseDir

    Synopsis:    Close directory file descriptor

Declaration:     function  CloseDir(p:  PDir)  :  Integer

    Visibility:   default

Description:     CloseDir closes the directory pointed to by p.  It returns zero if the directory was closed
                succesfully, -1 otherwise.

                For an example, see OpenDir (1043   ).

       Errors:   Errors are returned in LinuxError.

    See also:    OpenDir (1043   ), ReadDir (1046   ), SeekDir (1048   ), TellDir (1065   )
                23.12.13           CreateShellArgV

    Synopsis:    Create an array of null-terminated strings

Declaration:     function  CreateShellArgV(const  prog:  String)  :  ppchar
                function  CreateShellArgV(const  prog:  Ansistring)  :  ppchar

    Visibility:   default



                                                                                1003

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
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 (1051   )


                Listing:  ./olinuxex/ex61.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 6 1 ;


                {   Example       p r o g r a m t o  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 o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.14           Dirname

    Synopsis:    Extract directory part from filename

Declaration:     function  Dirname(const  path:  PathStr)  :  PathStr

    Visibility:   default

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 (997  ), FExpand (1018   )


                Listing:  ./olinuxex/ex47.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   Program       t o  d e m o n s t r a t et h e  DirName       f u n c t i o n. }


                Uses     o l d l i n u x;
                                                                                1004

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________


                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 p r o g r a m i s  i n   d i r e c t o r y:   ' ,Dirname     ( S ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.15           Dup

    Synopsis:    Duplicate a file handle

Declaration:     function  Dup(oldfile:  LongInt;var  newfile:  LongInt)  :  Boolean
                function  Dup(var  oldfile:  text;var  newfile:  text)  :  Boolean
                function  Dup(var  oldfile:  File;var  newfile:  File)  :  Boolean

    Visibility:   default

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  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 (1006   )


                Listing:  ./olinuxex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  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 o l d 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 nt o   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 t o  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                1005

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.16           Dup2

    Synopsis:    Duplicate one filehandle to another

Declaration:     function  Dup2(oldfile:  LongInt;newfile:  LongInt)  :  Boolean
                function  Dup2(var  oldfile:  text;var  newfile:  text)  :  Boolean
                function  Dup2(var  oldfile:  File;var  newfile:  File)  :  Boolean

    Visibility:   default

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 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 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 (1005   )


                Listing:  ./olinuxex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  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 o l d 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  t o  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 nt o   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 t o  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     t o  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___.____________________________________________________________________________________________________________*
 *___________

                23.12.17           EpochToLocal

    Synopsis:    Convert epoch time to local time


                                                                                1006

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Declaration:     procedure  EpochToLocal(epoch:  LongInt;var  year:  Word;var  month:  Word;
                                                    var  day:  Word;var  hour:  Word;var  minute:  Word;
                                                    var  second:  Word)

    Visibility:  default

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 (1027   ), LocalToEpoch (1037   ), GetTime (1031   ), GetDate (1024   )


                Listing:  ./olinuxex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  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     o l d 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   ;


                 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 td a t e  :   ' ,Day  : 2 , '/ ' ,Month    : 2 , '/ ' ,Y e a r : 4 ) ;
                    W r i t e l n ( ' C u r r e n tt i m e  :   ' ,Hour   : 2 , ': ' ,m i n u t e: 2 ,' : ' ,s e c o n d s: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.18           Execl

    Synopsis:    Execute process (using argument list)

Declaration:     procedure  Execl(const  Todo:  String)
                procedure  Execl(const  Todo:  Ansistring)

    Visibility:   default

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).



                                                                                1007

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    See also:    Execve (1011   ), Execv (1010   ), Execvp (1012   ), Execle (1008   ), Execlp (1009   ), Fork (1020   )


                Listing:  ./olinuxex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                {   Program       t o  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     o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.19           Execle

    Synopsis:    Execute process (using argument list, environment)

Declaration:     procedure  Execle(Todo:  String;Ep:  ppchar)
                procedure  Execle(Todo:  AnsiString;Ep:  ppchar)

    Visibility:   default

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:


                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 (1011   ), Execv (1010   ), Execvp (1012   ), Execl (1007   ), Execlp (1009   ), Fork (1020   )


                Listing:  ./olinuxex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   Program       t o  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     o l d 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 }



                                                                                1008

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                    {   '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 n v p  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' , e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.20           Execlp

    Synopsis:    Execute process (using argument list, environment; search path)

Declaration:     procedure  Execlp(Todo:  String;Ep:  ppchar)
                procedure  Execlp(Todo:  Ansistring;Ep:  ppchar)

    Visibility:   default

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 (1011   ), Execv (1010   ), Execvp (1012   ), Execle (1008   ), Execl (1007   ), Fork (1020   )


                Listing:  ./olinuxex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;


                {   Program       t o  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     o l d 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.}
                    {  e n v p  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 ' ,e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                1009

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.21           Execv

    Synopsis:    Execute process

Declaration:     procedure  Execv(const  path:  PathStr;args:  ppchar)
                procedure  Execv(const  path:  AnsiString;args:  ppchar)

    Visibility:   default

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 (1011   ), Execvp (1012   ), Execle (1008   ), Execl (1007   ), Execlp (1009   ), Fork (1020   )


                Listing:  ./olinuxex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v  f u n c t i o n. }


                Uses     o l d l i n u x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    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}
                    E x e c v (  '/ b i n/ l s ', pp ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1010

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.22           Execve

    Synopsis:    Execute process using environment

Declaration:     procedure  Execve(Path:  PathStr;args:  ppchar;ep:  ppchar)
                procedure  Execve(Path:  AnsiString;args:  ppchar;ep:  ppchar)
                procedure  Execve(path:  pchar;args:  ppchar;ep:  ppchar)

    Visibility:   default

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:


                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 (1011   ),  Execv (1010   ),  Execvp (1012   ),  Execle (1008   ),  Execl (1007   ),  Execlp (1009   ),
                Fork (1020   )


                Listing:  ./olinuxex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   Program       t o  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     o l d l i n u x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    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  , e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________
                                                                                1011

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.23           Execvp

    Synopsis:    Execute process, search path

Declaration:     procedure  Execvp(Path:  PathStr;Args:  ppchar;Ep:  ppchar)
                procedure  Execvp(Path:  AnsiString;Args:  ppchar;Ep:  ppchar)

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  The executable
                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 (1011   ), Execv (1010   ), Execle (1008   ), Execl (1007   ), Execlp (1009   ), Fork (1020   )


                Listing:  ./olinuxex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v p f u n c t i o n.  }


                Uses     o l d l i n u x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' l s ';
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    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.  }
                    E x e c v p ( ' l s ', pp , e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________
                                                                                1012

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.24           ExitProcess

    Synopsis:    Exit the current process

Declaration:     procedure  ExitProcess(val:  LongInt)

    Visibility:   default

Description:     ExitProcess exits the currently running process, and report Val as the exit status.

 Remark:         If this call is executed,  the normal unit finalization code will not be executed.  This may
                lead to unexpected errors and stray files on your system.  It is therefore recommended to use
                the Halt call instead.

       Errors:   None.

    See also:    Fork (1020   ), ExecVE (1011   )
                23.12.25           Fcntl

    Synopsis:    File control operations.

Declaration:     function  Fcntl(Fd:  LongInt;Cmd:  LongInt)  :  LongInt
                procedure  Fcntl(Fd:  LongInt;Cmd:  LongInt;Arg:  LongInt)
                function  Fcntl(var  Fd:  Text;Cmd:  LongInt)  :  LongInt
                procedure  Fcntl(var  Fd:  Text;Cmd:  LongInt;Arg:  LongInt)

    Visibility:   default

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.

                F__GetFl     Read the descriptor's flags.

                F__GetOwn        Get the Process ID of the owner of a socket.

                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.
                                                                                1013

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.26           fdClose

    Synopsis:    Close file descriptor

Declaration:     function  fdClose(fd:  LongInt)  :  Boolean

    Visibility:   default

Description:     fdClose closes a file with file descriptor Fd.  The function returns True if the file was closed
                successfully, False otherwise.

                For an example, see fdOpen (1014   ).

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1014   ), fdRead (1015   ), fdWrite (1017   ), fdTruncate (1017   ), fdFlush (1014   ), fdSeek
                (1016   )
                23.12.27           fdFlush

    Synopsis:    Flush kernel file buffer

Declaration:     function  fdFlush(fd:  LongInt)  :  Boolean

    Visibility:   default

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.

                For an example, see fdRead (1015   ).

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1014   ),  fdClose (1014   ),  fdRead (1015   ),  fdWrite (1017   ),  fdTruncate (1017   ),  fdSeek
                (1016   )
                23.12.28           fdOpen

    Synopsis:    Open file and return file descriptor

Declaration:     function  fdOpen(pathname:  String;flags:  LongInt)  :  LongInt
                function  fdOpen(pathname:  String;flags:  LongInt;mode:  LongInt)  :  LongInt
                function  fdOpen(pathname:  pchar;flags:  LongInt)  :  LongInt
                function  fdOpen(pathname:  pchar;flags:  LongInt;mode:  LongInt)  :  LongInt

    Visibility:   default

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__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.
                                                                                1014

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                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 descrip-
                      tor 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.

    See also:    fdClose (1014   ), fdRead (1015   ), fdWrite (1017   ), fdTruncate (1017   ), fdFlush (1014   ), fdSeek
                (1016   )


                Listing:  ./olinuxex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 9;


                {   Program       t o  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     o l d 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         o r  O p e n _C r e a t) ;
                    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 t o  f i l e !  ') ;
                        f d C l o s e(FD ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.29           fdRead

    Synopsis:    Read data from file descriptor

Declaration:     function  fdRead(fd:  LongInt;var  buf;size:  LongInt)  :  LongInt

    Visibility:   default


                                                                                1015

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
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 (1014   ), fdClose (1014   ), fdWrite (1017   ), fdTruncate (1017   ), fdFlush (1014   ), fdSeek
                (1016   )


                Listing:  ./olinuxex/ex20.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 0;


                {   Program       t o  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 e f u n c t i o n.s }


                Uses     o l d 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 y o r   o p e n _c r e a t,o 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  t o  1 0  do
                           i f  f d W r i t e ( 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     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  t o  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 ! ') ;
                                  H a l t( 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 }
                           {  F o r   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 y,o 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___.____________________________________________________________________________________________________________*
 *___________


                                                                                1016

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.30           fdSeek

    Synopsis:    Set file pointer position.

Declaration:     function  fdSeek(fd:  LongInt;pos:  LongInt;seektype:  LongInt)  :  LongInt

    Visibility:   default

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.

                For an example, see fdOpen (1014   ).

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1014   ), fdWrite (1017   ), fdClose (1014   ), fdRead (1015   ), fdTruncate (1017   ), fdFlush
                (1014   )
                23.12.31           fdTruncate

    Synopsis:    Truncate file on certain size.

Declaration:     function  fdTruncate(fd:  LongInt;size:  LongInt)  :  Boolean

    Visibility:   default

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 (1014   ), fdClose (1014   ), fdRead (1015   ), fdWrite (1017   ), fdFlush (1014   ), fdSeek (1016   )
                23.12.32           fdWrite

    Synopsis:    Write data to file descriptor

Declaration:     function  fdWrite(fd:  LongInt;const  buf;size:  LongInt)  :  LongInt

    Visibility:   default

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 (1014   ),  fdClose (1014   ),  fdRead (1015   ),  fdTruncate (1017   ),  fdSeek (1016   ),  fdFlush
                (1014   )


                                                                                1017

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.33           FD__Clr

    Synopsis:    Clears a filedescriptor in a set

Declaration:     procedure  FD_Clr(fd:  LongInt;var  fds:  fdSet)

    Visibility:   default

Description:     FD_Clr clears file descriptor fd in filedescriptor set fds.

                For an example, see Select (1048   ).

       Errors:   None.

    See also:    Select (1048   ), SelectText (1049   ), GetFS (1028   ), FD_ZERO (1018   ), FD_Set (1018   ), FD_IsSet
                (1018   )
                23.12.34           FD__IsSet

    Synopsis:    Check whether a filedescriptor is set

Declaration:     function  FD_IsSet(fd:  LongInt;var  fds:  fdSet)  :  Boolean

    Visibility:   default

Description:     FD_Set Checks whether file descriptor fd in filedescriptor set fds is set.

                For an example, see Select (1048   ).

       Errors:   None.

    See also:    Select (1048   ), SelectText (1049   ), GetFS (1028   ), FD_ZERO (1018   ), FD_Clr (1017   ), FD_Set
                (1018   )
                23.12.35           FD__Set

    Synopsis:    Set a filedescriptor in a set

Declaration:     procedure  FD_Set(fd:  LongInt;var  fds:  fdSet)

    Visibility:   default

Description:     FD_Set sets file descriptor fd in filedescriptor set fds.

                For an example, see Select (1048   ).

       Errors:   None.

    See also:    Select (1048   ), SelectText (1049   ), GetFS (1028   ), FD_ZERO (1018   ), FD_Clr (1017   ), FD_IsSet
                (1018   )
                23.12.36           FD__Zero

    Synopsis:    Clear all file descriptors in set

Declaration:     procedure  FD_Zero(var  fds:  fdSet)

    Visibility:   default

Description:     FD_ZERO clears all the filedescriptors in the file descriptor set fds.

                For an example, see Select (1048   ).



                                                                                1018

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
       Errors:   None.

    See also:    Select  (1048   ),  SelectText  (1049   ),  GetFS  (1028   ),  FD_Clr  (1017   ),  FD_Set  (1018   ),  FD_IsSet
                (1018   )
                23.12.37           FExpand

    Synopsis:    Expand filename to fully qualified path

Declaration:     function  FExpand(const  Path:  PathStr)  :  PathStr

    Visibility:   default

Description:     FExpand expands Path to a full path,  starting from root,  eliminating directory references
                such as .  and ..  from the result.

       Errors:   None

    See also:    BaseName (997  ), DirName (1004   )


                Listing:  ./olinuxex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  FExpand       f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( ' T h i s p r o g r a m i s  i n   :  ' ,FExpand      (Paramstr       ( 0 ) ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.38           Flock

    Synopsis:    Lock a file (advisory lock)

Declaration:     function  Flock(fd:  LongInt;mode:  LongInt)  :  Boolean
                function  Flock(var  T:  text;mode:  LongInt)  :  Boolean
                function  Flock(var  F:  File;mode:  LongInt)  :  Boolean

    Visibility:   default

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 (1013   )



                                                                                1019

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.39           FNMatch

    Synopsis:    Check whether filename matches wildcard specification

Declaration:     function  FNMatch(const  Pattern:  String;const  Name:  String)  :  Boolean

    Visibility:   default

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 (1021   ), FExpand (1018   )


                Listing:  ./olinuxex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   Program       t o  d e m o n s t r a t et h e  FNMatch       f u n c t i o n. }


                Uses     o l d l i n u x;


                    P r o c e d u r eTestMatch       ( 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  n o t  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___.____________________________________________________________________________________________________________*
 *___________

                23.12.40           Fork

    Synopsis:    Create child process

Declaration:     function  Fork  :  LongInt

    Visibility:   default

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 (1030   )).



                                                                                1020

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
       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 (1011   ), Clone (1001   )
                23.12.41           FReName

    Synopsis:    Rename file

Declaration:     function  FReName(OldName:  Pchar;NewName:  Pchar)  :  Boolean
                function  FReName(OldName:  String;NewName:  String)  :  Boolean

    Visibility:   default

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 (1066   )
                23.12.42           FSearch

    Synopsis:    Search for file in search path.

Declaration:     function  FSearch(const  path:  PathStr;dirlist:  String)  :  PathStr

    Visibility:   default

                                                                                1021

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Description:     FSearch 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 (997  ), DirName (1004   ), FExpand (1018   ), FNMatch (1019   )


                Listing:  ./olinuxex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 6;


                {   Program       t o  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     o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.43           FSplit

    Synopsis:    Split filename into path, name and extension

Declaration:     procedure  FSplit(const  Path:  PathStr;var  Dir:  DirStr;var  Name:  NameStr;
                                           var  Ext:  ExtStr)

    Visibility:   default

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 (1021   )


                Listing:  ./olinuxex/ex67.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                 u s e s o l d l i n u x;


                {   Program       t o  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    ,E x t   :  s t r i n g;


                 b e g i n
                    F S p l i t(ParamStr      ( 1 ) ,Path   ,Name    , E x t) ;
                    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: ' ,E x t ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1022

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.44           FSStat

    Synopsis:    Retrieve filesystem information.

Declaration:     function  FSStat(Path:  PathStr;var  Info:  Statfs)  :  Boolean
                function  FSStat(Fd:  LongInt;var  Info:  Statfs)  :  Boolean

    Visibility:   default

Description:     FSStat returns 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.

                sys__eaccess     Search permission is denied for component inPath.

                sys__eloop     A circular symbolic link was encountered in Path.

                sys__eio   An error occurred while reading from the filesystem.

    See also:    FStat (1023   ), LStat (1038   )


                Listing:__./olinuxex/ex30.pp_______________________________________________________________________________________*
 *___________

                program       E x a m p l e 3 0;


                {   Program       t o  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 o l d 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 ton    f i l e  ' '' ,s , ' ' '. ' ) ;
                        w r i t e l n(  'f s t y p e   :   ', i n f o. f s t y p e) ;
                        w r i t e l n(  'b s i z e     :   ', i n f o. b s i z e) ;
                        w r i t e l n(  'b f r e e     :   ', i n f o. b f r e e) ;
                        w r i t e l n(  'b a v a i l   :   ', i n f o. b a v a i l) ;
                        w r i t e l n(  'f i l e s     :   ', i n f o. f i l e s) ;
                        w r i t e l n(  'f f r e e     :   ', i n f o. f f r e e) ;
                        w r i t e l n(  'f s i d       :   ', i n f o. f s i d) ;
                        w r i t e l n(  'Namelen       :   ', i n f o. n a m e l e n) ;
                        w r i t e ( 'Type     name     o f   f i l e t o  do    f s s t a t.  (q   q u i t s)  : ') ;
                        r e a d l n (s )
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________
                                                                                1023

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.45           FStat

    Synopsis:    Retrieve information about a file

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

    Visibility:   default

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.

       Errors:   LinuxError is used to report errors.


                sys__enoent      Path does not exist.


    See also:    FSStat (1022   ), LStat (1038   )


                Listing:  ./olinuxex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 8;


                {   Program       t o  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 o l d 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  t o  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 o.i n o ) ;
                    w r i t e l n ( 'Mode           :  ' , i n f o.mode   ) ;
                    w r i t e l n ( ' n l i n k     :  ' , i n f o.n l i n k) ;
                    w r i t e l n ( ' u i d         :  ' , i n f o.u i d ) ;
                    w r i t e l n ( ' g i d         :  ' , i n f o.g i d ) ;
                    w r i t e l n ( ' r d e v       :  ' , i n f o.r d e v) ;
                    w r i t e l n ( ' S i z e       :  ' , i n f o.s i z e) ;



                                                                                1024

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                    w r i t e l n ( ' B l k s i z e :  ' , i n f o.b l k s z e) ;
                    w r i t e l n ( ' B l o c k s   :  ' , i n f o.b l o c k s) ;
                    w r i t e l n ( 'a t i m e      :  ' , i n f o.a t i m e) ;
                    w r i t e l n ( 'mtime          :  ' , i n f o.mtime    ) ;
                    w r i t e l n ( ' c t i m e     :  ' , i n f o.c t i m e) ;
                    {  Remove       f i l e }
                    e r a s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.46           GetDate

    Synopsis:    Return the system date

Declaration:     procedure  GetDate(var  Year:  Word;var  Month:  Word;var  Day:  Word)

    Visibility:   default

Description:     Returns the current date.

       Errors:   None

    See also:    GetEpochTime (1027   ), GetTime (1031   ), GetDateTime (1025   ), EpochToLocal (1006   )


                Listing:  ./olinuxex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t D a t e f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    Year    ,  Month    ,  Day    :  Word    ;


                 b e g i n
                  G e t D a t e ( Year   ,  Month    ,  Day   ) ;
                  W r i t e l n ( ' Date     :  ' ,Day   : 2 ,'/  ', Month    : 2 ,'/  ', Y e a r: 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.47           GetDateTime

    Synopsis:    Return system date and time

Declaration:     procedure  GetDateTime(var  Year:  Word;var  Month:  Word;var  Day:  Word;
                                                   var  hour:  Word;var  minute:  Word;var  second:  Word)

    Visibility:   default

Description:     Returns  the  current  date  and  time.  The  time  is  corrected  for  the  local  time  zone.  This
                procedure is equivalent to the GetDate (1024   ) and GetTime calls.

       Errors:   None

    See also:    GetEpochTime (1027   ), GetTime (1031   ), EpochToLocal (1006   ), GetDate (1024   )


                Listing:  ./olinuxex/ex60.pp

                                                                                1025

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  d e m o n s t r a t et h e  GetDateTime          f u n c t i o n. }


                Uses     o l d 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 ,'/  ', Y e a r: 4 ) ;
                  W r i t e l n ( ' Time     :  ' ,Hour    : 2 ,' :' ,Min   : 2 ,' : ' ,S e c: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.48           GetDomainName

    Synopsis:    Return current domain name

Declaration:     function  GetDomainName  :  String

    Visibility:   default

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 (1029   )


                Listing:  ./olinuxex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   Program       t o  d e m o n s t r a t et h e  GetDomainName            f u n c t i o n. }


                Uses     o l d 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 m a c h i n e  i s  :  ' ,GetDomainName          ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.49           GetEGid

    Synopsis:    Return effective group ID

Declaration:     function  GetEGid  :  LongInt

    Visibility:   default

Description:     Get the effective group ID of the currently running process.

       Errors:   None.

    See also:    GetGid (1029   )


                Listing:  ./olinuxex/ex18.pp



                                                                                1026

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  G e t G i d and    G e t E G i d f u n c t i o n s. }


                Uses     o l d 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 eg r o u p  I d  =   ' ,g e t e g i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.50           GetEnv

    Synopsis:    Return value of environment variable.

Declaration:     function  GetEnv(P:  String)  :  Pchar

    Visibility:   default

Description:     GetEnv  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.


                Listing:  ./olinuxex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 1;


                {   Program       t o  d e m o n s t r a t et h e  GetEnv      f u n c t i o n.  }


                Uses     o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.51           GetEpochTime

    Synopsis:    Return the current unix time

Declaration:     function  GetEpochTime  :  LongInt

    Visibility:   default

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 (1006   ), GetTime (1031   )


                Listing:  ./olinuxex/ex1.pp



                                                                                1027

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  d e m o n s t r a t et h e  GetEpochTime           f u n c t i o n. }


                Uses     o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.52           GetEUid

    Synopsis:    Return effective user ID

Declaration:     function  GetEUid  :  LongInt

    Visibility:   default

Description:     Get the effective user ID of the currently running process.

       Errors:   None.

    See also:    GetUid (1033   )


                Listing:  ./olinuxex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  G e t U i d and    GetEUid       f u n c t i o n s. }


                Uses     o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.53           GetFS

    Synopsis:    Return file selector

Declaration:     function  GetFS(var  T:  Text)  :  LongInt
                function  GetFS(var  F:  File)  :  LongInt

    Visibility:   default

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 (1048   ) call or so.

       Errors:   In case the file was not opened, then -1 is returned.

    See also:    Select (1048   )


                Listing:  ./olinuxex/ex34.pp


                                                                                1028

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  S e l e c t T e x tf u n c t i o n.  }


                Uses     o l d 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    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  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 }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s< ENTER    >   k e y  i n  l e s s  t h a n 2   s 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.54           GetGid

    Synopsis:    Return real group ID

Declaration:     function  GetGid  :  LongInt

    Visibility:   default

Description:     Get the real group ID of the currently running process.

       Errors:   None.

    See also:    GetEGid (1026   )


                Listing:  ./olinuxex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  G e t G i d and    G e t E G i d f u n c t i o n s. }


                Uses     o l d 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 eg r o u p  I d  =   ' ,g e t e g i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.55           GetHostName

    Synopsis:    Return host name

Declaration:     function  GetHostName  :  String

    Visibility:   default



                                                                                1029

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
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 (1025   )


                Listing:  ./olinuxex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 0;


                {   Program       t o  d e m o n s t r a t et h e  GetHostName          f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( 'Name     o f   t h i s m a c h i n e i s  :   ' ,GetHostName         ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.56           GetLocalTimezone

    Synopsis:    Return local timzeone information

Declaration:     procedure  GetLocalTimezone(timer:  LongInt;var  leap_correct:  LongInt;
                                                           var  leap_hit:  LongInt)
                procedure  GetLocalTimezone(timer:  LongInt)

    Visibility:   default

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 (1032   ), ReadTimezoneFile (1048   )
                23.12.57           GetPid

    Synopsis:    Return current process ID

Declaration:     function  GetPid  :  LongInt

    Visibility:   default

Description:     Get the Process ID of the currently running process.

       Errors:   None.

    See also:    GetPPid (1030   )


                Listing:  ./olinuxex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  G e t P i d,  G e t P P i d f u n c t i o n. }


                Uses     o l d l i n u x;



                                                                                1030

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________


                 b e g i n
                    W r i t e l n ( ' P r o c e s sI 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.58           GetPPid

    Synopsis:    Return parent process ID

Declaration:     function  GetPPid  :  LongInt

    Visibility:   default

Description:     Get the Process ID of the parent process.

       Errors:   None.

    See also:    GetPid (1030   )


                Listing:  ./olinuxex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  G e t P i d,  G e t P P i d f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( ' P r o c e s sI 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.59           GetPriority

    Synopsis:    Return process priority

Declaration:     function  GetPriority(Which:  Integer;Who:  Integer)  :  Integer

    Visibility:   default

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.

                For an example, see Nice (1042   ).

       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 (1050   ), Nice (1042   )



                                                                                1031

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.60           GetTime

    Synopsis:    Return current system time

Declaration:     procedure  GetTime(var  hour:  Word;var  min:  Word;var  sec:  Word;
                                            var  msec:  Word;var  usec:  Word)
                procedure  GetTime(var  hour:  Word;var  min:  Word;var  sec:  Word;
                                            var  sec100:  Word)
                procedure  GetTime(var  hour:  Word;var  min:  Word;var  sec:  Word)

    Visibility:   default

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 (1027   ), GetDate (1024   ), GetDateTime (1025   ), EpochToLocal (1006   )


                Listing:__./olinuxex/ex5.pp________________________________________________________________________________________*
 *___________

                Program       Example5       ;


                {   Program       t o  d e m o n s t r a t et h e  GetTime       f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    Hour    ,  Minute     ,  S e c o n d :  Word    ;


                 b e g i n
                    GetTime       ( Hour   ,  Minute     ,  S e c o n d) ;
                    W r i t e l n ( 'Time     :   ' ,Hour   : 2 , ': ' ,M i n u t e: 2 ,' : ' ,S e c o n d: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.61           GetTimeOfDay

    Synopsis:    Return kernel time of day in GMT

Declaration:     procedure  GetTimeOfDay(var  tv:  timeval)
                function  GetTimeOfDay  :  LongInt

    Visibility:   default

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 (1031   ).

       Errors:   None.

    See also:    GetTime (1031   ), GetTimeOfDay (1032   )



                                                                                1032

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.62           GetTimezoneFile

    Synopsis:    Return name of timezone information file

Declaration:     function  GetTimezoneFile  :  String

    Visibility:   default

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 (1048   )
                23.12.63           GetUid

    Synopsis:    Return current user ID

Declaration:     function  GetUid  :  LongInt

    Visibility:   default

Description:     Get the real user ID of the currently running process.

       Errors:   None.

    See also:    GetEUid (1027   )


                Listing:  ./olinuxex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  G e t U i d and    GetEUid       f u n c t i o n s. }


                Uses     o l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.64           Glob

    Synopsis:    Find filenames matching a wildcard pattern

Declaration:     function  Glob(const  path:  PathStr)  :  pglob

    Visibility:   default



                                                                                1033

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
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 (1034   )


                Listing:  ./olinuxex/ex49.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   Program       t o  d e m o n s t r a t et h e  G l o b  and    G l o b F r e e f u n c t i o n.s }


                Uses     o l d l i n u x;


                Var    G1  ,G2    :  PGlob    ;


                 b e g i n
                    G1 :=  G l o b  ( '* ' ) ;
                    i f  L i n u x E r r o r=0  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___.____________________________________________________________________________________________________________*
 *___________

                23.12.65           Globfree

    Synopsis:    Free result of Glob (1033   ) call

Declaration:     procedure  Globfree(var  p:  pglob)

    Visibility:   default

Description:     Releases the memory, occupied by a pglob structure.  P is set to nil.

                For an example, see Glob (1033   ).

       Errors:   None

    See also:    Glob (1033   )
                23.12.66           IOCtl

    Synopsis:    General kernel IOCTL call.

Declaration:     function  IOCtl(Handle:  LongInt;Ndx:  LongInt;Data:  Pointer)  :  Boolean



                                                                                1034

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    Visibility:  default

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


                Listing:__./olinuxex/ex54.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 4;


                 u s e s o l d l i n u x;


                {   Program       t o  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 r( t 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 t r( t i 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.67           IOperm

    Synopsis:    Set permission on IO ports

Declaration:     function  IOperm(From:  Cardinal;Num:  Cardinal;Value:  LongInt)  :  Boolean

    Visibility:   default

Description:     IOperm  sets  permissions  on  Num  ports  starting  with  port  From  to  Value.   The  function
                returns True if the call was successfull, False otherwise.

                Note:


                      oThis works ONLY as root.

                      oOnly the first 0x03ff ports can be set.

                      oWhen doing a Fork (1020   ), the permissions are reset.  When doing a Execve (1011   ) they
                       are kept.


       Errors:   Errors are returned in LinuxError
                23.12.68           IoPL

    Synopsis:    Set I/O privilege level

Declaration:     function  IoPL(Level:  LongInt)  :  Boolean

    Visibility:   default

Description:     IoPL sets the I/O privilige level.  It is intended for completeness only, one should normally
                not use it.



                                                                                1035

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.69           IsATTY

    Synopsis:    Check if filehandle is a TTY (terminal)

Declaration:     function  IsATTY(Handle:  LongInt)  :  Boolean
                function  IsATTY(var  f:  text)  :  Boolean

    Visibility:   default

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 (1034   ), TTYName (1065   )
                23.12.70           Kill

    Synopsis:    Send a signal to a process

Declaration:     function  Kill(Pid:  LongInt;Sig:  LongInt)  :  Integer

    Visibility:   default

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 (1052   ), Signal (1053   )
                23.12.71           Link

    Synopsis:    Create a hard link to a file

Declaration:     function  Link(OldPath:  PathStr;NewPath:  PathStr)  :  Boolean

    Visibility:   default

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.
                                                                                1036

            ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'______________________*
 *_______________
            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 another entry.

            sys__eperm     OldPath points to .  or ..  of a directory.


See also:    SymLink (1057   ), UnLink (1066   )


            Listing:  ./olinuxex/ex21.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program       E x a m p l e 2 1;


            {   Program       t o  d e m o n s t r a t et h e  L i n k  and    U n L i n k f u n c t i o n s. }


            Uses     o l d l i n u x;


            Var    F   :  T e x t ;
                   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 t o  t e s t. t 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 snew   . 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 ') ;
                R e s e t ( 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___.________________________________________________________________________________________________________________*
 *_______

            23.12.72           LocalToEpoch

Synopsis:    Convert local time to epoch (unix) time



                                                                            1037

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Declaration:     function  LocalToEpoch(year:  Word;month:  Word;day:  Word;hour:  Word;
                                                  minute:  Word;second:  Word)  :  LongInt

    Visibility:  default

Description:     Converts  the  Local  time  to  epoch  time  (=Number  of  seconds  since  00:00:00  ,  January  1,
                1970 ).

       Errors:   None

    See also:    GetEpochTime (1027   ), EpochToLocal (1006   ), GetTime (1031   ), GetDate (1024   )


                Listing:  ./olinuxex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  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     o l d 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     (  'Y e a r       :   ') ; r e a d l n(Y e a r) ;
                    Write     (  'Month         :   ') ; r e a d l n(Month    ) ;
                    Write     (  'Day           :   ') ; r e a d l n(Day  ) ;
                    Write     (  'Hour          :   ') ; r e a d l n(Hour   ) ;
                    Write     (  'M i n u t e   :   ') ; r e a d l n(M i n u t e) ;
                    Write     (  'S e o n d s   :   ') ; r e a d l n(S e c o n d) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                23.12.73           Lstat

    Synopsis:    Return information about symbolic link.  Do not follow the link

Declaration:     function  Lstat(Filename:  PathStr;var  Info:  Stat)  :  Boolean

    Visibility:   default

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 (1023   ), FSStat (1022   )


                Listing:  ./olinuxex/ex29.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 9;


                {   Program       t o  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. }

                                                                                1038

______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___
 u s e s o l d 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  t o  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 o.i n o ) ;
    w r i t e l n ( 'Mode           :  ' , i n f o.mode   ) ;
    w r i t e l n ( ' n l i n k     :  ' , i n f o.n l i n k) ;
    w r i t e l n ( ' u i d         :  ' , i n f o.u i d ) ;
    w r i t e l n ( ' g i d         :  ' , i n f o.g i d ) ;
    w r i t e l n ( ' r d e v       :  ' , i n f o.r d e v) ;
    w r i t e l n ( ' S i z e       :  ' , i n f o.s i z e) ;
    w r i t e l n ( ' B l k s i z e :  ' , i n f o.b l k s z e) ;
    w r i t e l n ( ' B l o c k s   :  ' , i n f o.b l o c k s) ;
    w r i t e l n ( 'a t i m e      :  ' , i n f o.a t i m e) ;
    w r i t e l n ( 'mtime          :  ' , i n f o.mtime    ) ;
    w r i t e l n ( ' c t i m e     :  ' , i n f o.c 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 o.i n o ) ;
    w r i t e l n ( 'Mode           :  ' , i n f o.mode   ) ;
    w r i t e l n ( ' n l i n k     :  ' , i n f o.n l i n k) ;
    w r i t e l n ( ' u i d         :  ' , i n f o.u i d ) ;
    w r i t e l n ( ' g i d         :  ' , i n f o.g i d ) ;
    w r i t e l n ( ' r d e v       :  ' , i n f o.r d e v) ;
    w r i t e l n ( ' S i z e       :  ' , i n f o.s i z e) ;
    w r i t e l n ( ' B l k s i z e :  ' , i n f o.b l k s z e) ;
    w r i t e l n ( ' B l o c k s   :  ' , i n f o.b l o c k s) ;
    w r i t e l n ( 'a t i m e      :  ' , i n f o.a t i m e) ;
    w r i t e l n ( 'mtime          :  ' , i n f o.mtime    ) ;
    w r i t e l n ( ' c t i m e     :  ' , i n f o.c 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' ) ;
                                                                1039

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.74           mkFifo

    Synopsis:    Create FIFO (named pipe) in file system

Declaration:     function  mkFifo(pathname:  String;mode:  LongInt)  :  Boolean

    Visibility:   default

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 (1045   ), MkFifo (1039   )
                23.12.75           MMap

    Synopsis:    Create memory map of a file

Declaration:     function  MMap(const  m:  tmmapargs)  :  LongInt

    Visibility:   default

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.

                       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:



                                                                                1040

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                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 writing.

                Sys__EAGAIN          fd is locked, or too much memory is locked.

                Sys__ENOMEM            Not enough memory for this operation.


    See also:    MUnMap (1041   )


                Listing:  ./olinuxex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   Program       t o  d e m o n s t r a t et h e  MMap     f u n c t i o n. }


                Uses     o l d 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 e.t x t' ,O p e n _w r O n l y o r   o p e n _c r e a t) ;
                    I f  f d=-1     then
                       H a l t ( 1 ) ;
                    I f  f d W r i t e(f d ,S [ 1 ] ,Len  )=-1     then
                       H a l t ( 2 ) ;
                    f d C l o s e(f d ) ;
                    fdOpen    (  't e s t f i l e.t x t' ,O p e n _r d O n l y) ;
                    i f  f d=-1     then
                       H a l t ( 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         o r  PROT_WRITE       ;
                    P := P c h a r(mmap    ( a r g s) ) ;
                    I f  l o n g i n t(P )=-1     then
                       H a l t ( 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
                       H a l t( L i n u x E r r o r) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.76           MUnMap

    Synopsis:    Unmap previously mapped memory block

Declaration:     function  MUnMap(P:  Pointer;Size:  LongInt)  :  Boolean



                                                                                1041

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    Visibility:  default

Description:     MUnMap  unmaps  the  memory  block  of  size  Size,  pointed  to  by  P,  which  was  previously
                allocated with MMap (1040   ).

                The function returns True if successful, False otherwise.

                For an example, see MMap (1040   ).

       Errors:   In case of error the function returns False and LinuxError is set to an error value.  See
                MMap (1040   ) for possible error values.

    See also:    MMap (1040   )
                23.12.77           NanoSleep

    Synopsis:    Suspend process for a short time

Declaration:     function  NanoSleep(const  req:  timespec;var  rem:  timespec)  :  LongInt

    Visibility:   default

Description:     NanoSleep suspends the process till a time period as specified in req has passed.  Then the
                function  returns.  If  the  call  was  interrupted  (e.g.  by  some  signal)  then  the  function  may
                return earlier, and rem will contain the remaining time till the end of the intended period.
                In this case the return value will be -1, and LinuxError will be set to EINTR

                If the function returns without error, the return value is zero.

       Errors:   If the call was interrupted, -1 is returned, and LinuxError is set to EINTR. If invalid time
                values were specified, then -1 is returned and LinuxError is set to EINVAL.

    See also:    Pause (1045   ), Alarm (994  )


                Listing:  ./olinuxex/ex72.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 7 2;


                {   Program       t o  d e m o n s t r a t et h e  N a n o S l e e p f u n c t i o n. }


                 u s e s o l d l i n u x;


                Var
                    Req  , Rem    :  TimeSpec       ;
                    Res    :   L o n g i n t;


                 b e g i n
                    With     Req    do
                        b e g i n
                        t v _s e c: = 1 0 ;
                        t v _n s e c: = 1 0 0 ;
                       end   ;
                    Write    ( 'N a n o S l e e p r e t u r n e d :  ' ) ;
                    F l u s h(Output     ) ;
                    Res  : = (N a n o S l e e p(Req  , rem  ) ) ;
                    W r i t e l n(r e s) ;
                    I f  ( r e s<>0)     then
                       With     rem    do
                           b e g i n
                           W r i t e l n(' R e m a i n i n gs e c o n d s        :   ' ,t v _s e c ) ;
                                                                                1042

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                           W r i t e l n(' R e m a i n i n gn a n o s e c o n d s:   ' ,t v _n s e c) ;
                           end  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.78           Nice

    Synopsis:    Set process priority

Declaration:     procedure  Nice(N:  Integer)

    Visibility:   default

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 (1031   ), SetPriority (1050   )


                Listing:  ./olinuxex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   Program       t o  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     o l d 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 yt o  5 ' ) ;
                    s e t p r i o r i t y( p r i o _p r o c e s s,g e t p i d, 5 ) ;
                    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 y( p r i o _p r o c e s s,g e t p i d) ) ;
                    w r i t e l n ( 'D o i n g  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 y( p r i o _p r o c e s s,g e t p i d) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.79           Octal

    Synopsis:    Convert octal to decimal value

Declaration:     function  Octal(l:  LongInt)  :  LongInt

    Visibility:   default

Description:     Octal will convert a number specified as an octal number to it's decimal value.

                This is useful for the Chmod (999  ) 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 (999  )


                Listing:  ./olinuxex/ex68.pp



                                                                                1043

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 8;


                {   Program       t o  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     o l d 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 l( 7 7 7 ) ) ;
                    W r i t e l n('Mode     6 4 4  :   ' ,  O c t a l( 6 4 4 ) ) ;
                    W r i t e l n('Mode     7 5 5  :   ' ,  O c t a l( 7 5 5 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.80           OpenDir

    Synopsis:    Open directory for reading

Declaration:     function  OpenDir(f:  pchar)  :  PDir
                function  OpenDir(f:  String)  :  PDir

    Visibility:   default

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 (1003   ), ReadDir (1046   ), SeekDir (1048   ), TellDir (1065   )


                Listing:  ./olinuxex/ex35.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   Program       t o  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     o l d l i n u x;


                Var    T h e D i r  :  P D i r;
                        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;


                 b e g i n
                    T h e D i r:= OpenDir     ( ' . / .' ) ;
                    Repeat
                        E n t r y:= T e l l D i r(T h e D i r) ;
                        A D i r e n t:=R e a d D i r ( T h e D i r) ;
                        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 a r(@name    [ 0 ] ) ) ;
                              end   ;
                    U n t i l  A D i r e n=t N i l;
                    Repeat



                                                                                1044

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                       Write      ( ' E n t r y No  .  you    w o u l d  l i k e t o  s e e  a g a i n ( - 1   t o  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( T h e D i r) ;
                           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 a r(@name     [ 0 ] ) ) ;
                                  end  ;
                       end   ;
                    U n t i l  E n t r y=-1;
                    C l o s e D i r (T h e D i r) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.81           Pause

    Synopsis:    Wait for a signal

Declaration:     procedure  Pause

    Visibility:   default

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.

                For an example, see Alarm (994  ).
                23.12.82           PClose

    Synopsis:    Close file opened with POpen (1045   )

Declaration:     function  PClose(var  F:  text)  :  LongInt
                function  PClose(var  F:  File)  :  LongInt

    Visibility:   default

Description:     PClose closes a file opened with POpen (1045   ).  It waits for the command to complete, and
                then returns the exit status of the command.

                For an example, see POpen (1045   )

       Errors:   LinuxError is used to report errors.  If it is different from zero, the exit status is not valid.

    See also:    POpen (1045   )
                23.12.83           POpen

    Synopsis:    Pipe file to standard input/output of program

Declaration:     procedure  POpen(var  F:  text;const  Prog:  String;rw:  Char)
                procedure  POpen(var  F:  File;const  Prog:  String;rw:  Char)



                                                                                1045

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    Visibility:  default

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 (1045   ).  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 (995  ), PClose (1045   )


                Listing:  ./olinuxex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   Program       t o  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 o l d 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 ga   s h e l l s c r i p t t o   w h i c h 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 b a c k  t o  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/ s h ' ) ;
                    w r i t e l n ( f , 'e c h o  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 , 'e c h o  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 f r o m  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  t o  1 0  do
                        w r i t e l n( f , 'T h i s  i s   w r i t t e nt o   t h e  p i p e,  and    s h o u l d a p p e a r on   *
 * 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 e ( f ) ) ;
                    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>  t o  r e m o v e 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.84           ReadDir

    Synopsis:    Read entry from directory
                                                                                1046

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Declaration:     function  ReadDir(p:  PDir)  :  pdirent

    Visibility:  default

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.

                For an example, see OpenDir (1043   ).

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1003   ), OpenDir (1043   ), SeekDir (1048   ), TellDir (1065   )
                23.12.85           ReadLink

    Synopsis:    Read destination of symbolic link

Declaration:     function  ReadLink(name:  pchar;linkname:  pchar;maxlen:  LongInt)  :  LongInt
                function  ReadLink(name:  PathStr)  :  PathStr

    Visibility:   default

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 translating 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 (1057   )


                Listing:  ./olinuxex/ex62.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   Program       t o  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     o l d l i n u x;


                Var    F   :  T e x t ;
                       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  ) ;



                                                                                1047

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                    W r i t e l n (F  , 'T h i s  i s  w r i t t e n t o  t e s t. t 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! ' ) ;
                    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 t o  :   ' ,S ) ;
                  {  Now     r e m o v e 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.86           ReadTimezoneFile

    Synopsis:    Read the timezone file and initialize time routines

Declaration:     procedure  ReadTimezoneFile(fn:  String)

    Visibility:   default

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 (1032   ), GetLocalTimezone (1030   )
                23.12.87           SeekDir

    Synopsis:    Seek to position in directory

Declaration:     procedure  SeekDir(p:  PDir;off:  LongInt)

    Visibility:   default

Description:     SeekDir sets the directory pointer to the off-th entry in the directory structure pointed to
                by p.

                For an example, see OpenDir (1043   ).

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1003   ), ReadDir (1046   ), OpenDir (1043   ), TellDir (1065   )
                23.12.88           Select

    Synopsis:    Wait for events on file descriptors
                                                                                1048

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Declaration:     function  Select(N:  LongInt;readfds:  pfdset;writefds:  pfdset;
                                        exceptfds:  pfdset;TimeOut:  ptimeval)  :  LongInt
                function  Select(N:  LongInt;readfds:  pfdset;writefds:  pfdset;
                                        exceptfds:  pfdset;TimeOut:  LongInt)  :  LongInt

    Visibility:  default

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 (1018   )FD_Clr (1017   ), FD_Set (1018   ) or FD_IsSet (1018   )
                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 descriptor 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 (1049   ), GetFS (1028   ), FD_ZERO (1018   ), FD_Clr (1017   ), FD_Set (1018   ), FD_IsSet
                (1018   )


                Listing:  ./olinuxex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  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     o l d l i n u x;


                Var    FDS     :  FDSet    ;


                 b e g i n
                    FD _Zero      (FDS   ) ;
                    FD _Set     ( 0 ,FDS   ) ;



                                                                                1049

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                    W r i t e l n ( ' P r e s s t h e < ENTER    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  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    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                    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   )  w o u l d 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.89           SelectText

    Synopsis:    Wait for event on typed ontyped file.

Declaration:     function  SelectText(var  T:  Text;TimeOut:  ptimeval)  :  LongInt
                function  SelectText(var  T:  Text;TimeOut:  LongInt)  :  LongInt

    Visibility:   default

Description:     SelectText executes the Select (1048   ) 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 (1048   ).  SYS_EBADF can also mean that the file wasn't opened.

    See also:    Select (1048   ), GetFS (1028   )
                23.12.90           SetDate

    Synopsis:    Set the current system date.

Declaration:     function  SetDate(Year:  Word;Month:  Word;Day:  Word)  :  Boolean

    Visibility:   default

Description:     SetDate sets the system date to year, month, day.  This is the kernel date, so it is in GMT.
                The time is not touched.  The function returns True if the call was executed corretly, False
                otherwise.

 Remark:         You must be root to execute this call.

       Errors:   Errors are returned in LinuxError (993  )

    See also:    GetDate (1024   ), SetTime (1051   ), SetDateTime (1050   )
                23.12.91           SetDateTime

    Synopsis:    Set the current system date and time

Declaration:     function  SetDateTime(Year:  Word;Month:  Word;Day:  Word;hour:  Word;
                                                 minute:  Word;second:  Word)  :  Boolean



                                                                                1050

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    Visibility:  default

Description:     SetDate sets the system date and time to year,  month,  day,  hour,  min,  Sec.  This is the
                kernel date/time,  so it is in GMT. The time is not touched.  The function returns True if
                the call was executed corretly, False otherwise.

 Remark:         You must be root to execute this call.

       Errors:   Errors are returned in LinuxError (993  )

    See also:    SetDate (1050   ), SetTime (1051   ), GetDateTime (1025   )
                23.12.92           SetPriority

    Synopsis:    Set process priority

Declaration:     procedure  SetPriority(Which:  Integer;Who:  Integer;What:  Integer)

    Visibility:   default

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 constants:


                Prio__Process       Who is interpreted as process ID

                Prio__PGrp       Who is interpreted as process group ID

                Prio__User      Who is interpreted as user ID


                Prio is a value in the range -20 to 20.

                For an example, see Nice (1042   ).

       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 (1031   ), Nice (1042   )
                23.12.93           SetTime

    Synopsis:    Set the current system time.

Declaration:     function  SetTime(Hour:  Word;Min:  Word;Sec:  Word)  :  Boolean

    Visibility:   default

Description:     SetTime sets the system time to hour, min, Sec.  This is the kernel time, so it is in GMT.
                The date is not touched.  The function returns True if the call was executed corretly, False
                otherwise.

 Remark:         You must be root to execute this call.

       Errors:   Errors are returned in LinuxError (993  )

    See also:    GetTime (1031   ), SetDate (1050   ), SetDateTime (1050   )



                                                                                1051

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.94           Shell

    Synopsis:    Execute and feed command to system shell

Declaration:     function  Shell(const  Command:  String)  :  LongInt
                function  Shell(const  Command:  AnsiString)  :  LongInt

    Visibility:   default

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  (1020   )  or  Execve  (1011   )
                calls.

       Errors:   Errors are reported in LinuxError.

    See also:    POpen (1045   ), Fork (1020   ), Execve (1011   )


                Listing:  ./olinuxex/ex56.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5 6;


                 u s e s o l d l i n u x;


                {   Program       t o  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  * . pp  ') ;
                    S := S h e l l  ( 'l s  - l   * .pp  ' ) ;
                    W r i t e l n ( 'Command        e x i t e d w w i t h s t a t u s :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.95           SigAction

    Synopsis:    Install signal handler

Declaration:     procedure  SigAction(Signum:  LongInt;Act:  PSigActionRec;
                                                OldAct:  PSigActionRec)

    Visibility:   default

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 processes
                       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.



                                                                                1052

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                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 (1054   ), SigPending (1054   ), SigSuspend (1056   ), Kill (1036   )


                Listing:  ./olinuxex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 7;


                {   Program       t o  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 f r o m  a n o t h e r t e r m i n a l t o  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  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }


                 u s e s o l d l i n u x;


                Var
                      oa , na   :   P S i g A c t i o n R e;c


                 P r o c e d u r eDoSig    ( 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 gs 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.s h:=  @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(nS 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    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.96           Signal

    Synopsis:    Install signal handler (deprecated)

Declaration:     function  Signal(Signum:  LongInt;Handler:  SignalHandler)  :  SignalHandler



                                                                                1053

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    Visibility:  default

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 (1052   ), Kill (1036   )


                Listing:  ./olinuxex/ex58.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 8;


                {   Program       t o  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 f r o m  a n o t h e r t e r m i n a l t o  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  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }


                 u s e s o l d l i n u x;


                 P r o c e d u r eDoSig    ( 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 gs 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    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.97           SigPending

    Synopsis:    Return set of currently pending signals

Declaration:     function  SigPending  :  SigSet

    Visibility:   default

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 (1052   ), SigProcMask (1054   ), SigSuspend (1056   ), Signal (1053   ), Kill (1036   )


                                                                                1054

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.98           SigProcMask

    Synopsis:    Set list of blocked signals

Declaration:     procedure  SigProcMask(How:  LongInt;SSet:  PSigSet;OldSSet:  PSigSet)

    Visibility:   default

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.


                sys__efault    SSet or OldSSet point to an adress outside the range of the process.

                sys__eintr    System call was interrupted.


    See also:    SigAction (1052   ), SigPending (1054   ), SigSuspend (1056   ), Kill (1036   )
                23.12.99           SigRaise

    Synopsis:    Raise a signal (send to current process)

Declaration:     procedure  SigRaise(Sig:  Integer)

    Visibility:   default

Description:     SigRaise sends a Sig signal to the current process.

       Errors:   None.

    See also:    Kill (1036   ), GetPid (1030   )


                Listing:  ./olinuxex/ex65.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 6 4;


                {   Program       t o  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 o l d l i n u x;


                Var
                      oa , na   :   P S i g A c t i o n R e;c


                 P r o c e d u r eDoSig    ( 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 gs 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.s h:=  @DoSig    ;



                                                                                1055

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                      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(nS 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 t o  s e l f. ' ) ;
                      S i g R a i s e(s i g u s r 1) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.100            SigSuspend

    Synopsis:    Set signal mask and suspend process till signal is received

Declaration:     procedure  SigSuspend(Mask:  SigSet)

    Visibility:   default

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

    See also:    SigAction (1052   ), SigProcMask (1054   ), SigPending (1054   ), Signal (1053   ), Kill (1036   )
                23.12.101            StringToPPChar

    Synopsis:    Split string in list of null-terminated strings

Declaration:     function  StringToPPChar(var  S:  String)  :  ppchar
                function  StringToPPChar(var  S:  AnsiString)  :  ppchar
                function  StringToPPChar(S:  Pchar)  :  ppchar

    Visibility:   default

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.

                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 (1003   ), Execve (1011   ), Execv (1010   )


                Listing:  ./olinuxex/ex70.pp

                                                                                1056

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   Program       t o  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     o l d 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 ea t  end  .
                    S :=  'T h i s  i s  a   s t r i n g w i t h w o r d s.   ';
                    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(P c h a r) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.102            SymLink

    Synopsis:    Create a symbolic link

Declaration:     function  SymLink(OldPath:  PathStr;NewPath:  PathStr)  :  Boolean

    Visibility:   default

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  permissions  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 does not 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.

                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 another entry.

                                                                                1057

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
    See also:    Link (1036   ), UnLink (1066   ), ReadLink (1046   )


                Listing:  ./olinuxex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   Program       t o  d e m o n s t r a t et h e  SymLink       and    U n L i n k f u n c t i o n s. }


                Uses     o l d l i n u x;


                Var    F   :  T e x t ;
                       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 t o  t e s t. t 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 snew   . t x t
                        P o i n t i n gnow    t o  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 c l i n k
                        p o i n t s t o  a  non  -  e x i s t e n tf i l e!  }
                    { $ i- }
                    R e s e t ( F ) ;
                    { $ i+ }
                    I f  I O R e s u l t=0  then
                        W r i t e l n(  'T h i s  s h o u l d n''t   h a p p e n') ;
                  {  Now     r e m o v e 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.103            SysCall

    Synopsis:    Execute system call.

Declaration:     function  SysCall(callnr:  LongInt;var  regs:  SysCallRegs)  :  LongInt

    Visibility:   default

Description:     SysCall can be used to execute a direct system call.  The call parameters must be encoded
                in regs and the call number must be specified by callnr.  The call result is returned, and
                any modified registers are in regs

       Errors:   None.

    See also:    SysCallregs (989  )
                23.12.104            Sysinfo

    Synopsis:    Return kernel system information



                                                                                1058

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Declaration:     function  Sysinfo(var  Info:  TSysinfo)  :  Boolean

    Visibility:  default

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.

                totalswap      total amount of swapspace.

                freeswap     amount of free swapspace.

                procs   number of current processes.


       Errors:   None.

    See also:    Uname (1066   )


                Listing:  ./olinuxex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 6 4;


                {   Example       t o  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     o l d 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
                       H a l t ( 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('L o a d s    :  ' ,L o a d s[ 1 ] ,' / ' ,L o a d s[ 2 ] ,'/  ', L o a d s[ 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 . ' ) ;



                                                                                1059

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.105            S__ISBLK

    Synopsis:    Is file a block device

Declaration:     function  S_ISBLK(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISBLK checks the file mode m to see whether the file is a block device file.  If so it returns
                True.

    See also:    FStat (1023   ), S_ISLNK (1060   ), S_ISREG (1061   ), S_ISDIR (1060   ), S_ISCHR (1060   ), S_ISFIFO
                (1060   ), S_ISSOCK (1061   )
                23.12.106            S__ISCHR

    Synopsis:    Is file a character device

Declaration:     function  S_ISCHR(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISCHR  checks  the  file  mode  m  to  see  whether  the  file  is  a  character  device  file.  If  so  it
                returns True.

    See also:    FStat (1023   ), S_ISLNK (1060   ), S_ISREG (1061   ), S_ISDIR (1060   ), S_ISBLK (1059   ), S_ISFIFO
                (1060   ), S_ISSOCK (1061   )
                23.12.107            S__ISDIR

    Synopsis:    Is file a directory

Declaration:     function  S_ISDIR(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISDIR checks the file mode m to see whether the file is a directory.  If so it returns True

    See also:    FStat (1023   ), S_ISLNK (1060   ), S_ISREG (1061   ), S_ISCHR (1060   ), S_ISBLK (1059   ), S_ISFIFO
                (1060   ), S_ISSOCK (1061   )
                23.12.108            S__ISFIFO

    Synopsis:    Is file a FIFO

Declaration:     function  S_ISFIFO(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISFIFO  checks  the  file  mode  m  to  see  whether  the  file  is  a  fifo  (a  named  pipe).  If  so  it
                returns True.

    See also:    FStat (1023   ), S_ISLNK (1060   ), S_ISREG (1061   ), S_ISCHR (1060   ), S_ISBLK (1059   ), S_ISDIR
                (1060   ), S_ISSOCK (1061   )



                                                                                1060

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.109            S__ISLNK

    Synopsis:    Is file a symbolic link

Declaration:     function  S_ISLNK(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISLNK checks the file mode m to see whether the file is a symbolic link.  If so it returns
                True

    See also:    FStat (1023   ), S_ISFIFO (1060   ), S_ISREG (1061   ), S_ISCHR (1060   ), S_ISBLK (1059   ), S_ISDIR
                (1060   ), S_ISSOCK (1061   )


                Listing:  ./olinuxex/ex53.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 3;


                {   Program       t o  d e m o n s t r a t et h e  S _ISLNK      f u n c t i o n. }


                Uses     o l d 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 _I S D I R( 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 rd 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 _I S F I F O( 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___.____________________________________________________________________________________________________________*
 *___________

                23.12.110            S__ISREG

    Synopsis:    Is file a regular file

Declaration:     function  S_ISREG(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISREG checks the file mode m to see whether the file is a regular file.  If so it returns True

    See also:    FStat (1023   ), S_ISFIFO (1060   ), S_ISLNK (1060   ), S_ISCHR (1060   ), S_ISBLK (1059   ), S_ISDIR
                (1060   ), S_ISSOCK (1061   )



                                                                                1061

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.111            S__ISSOCK

    Synopsis:    Is file a unix socket

Declaration:     function  S_ISSOCK(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISSOCK checks the file mode m to see whether the file is a socket.  If so it returns True.

    See also:    FStat (1023   ), S_ISFIFO (1060   ), S_ISLNK (1060   ), S_ISCHR (1060   ), S_ISBLK (1059   ), S_ISDIR
                (1060   ), S_ISREG (1061   )
                23.12.112            TCDrain

    Synopsis:    Terminal control:  Wait till all data was transmitted

Declaration:     function  TCDrain(fd:  LongInt)  :  Boolean

    Visibility:   default

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:    TCFlow  (1062   ),  TCFlush  (1062   ),  TCGetAttr  (1063   ),  TCGetPGrp  (1063   ),  TCSendBreak
                (1064   ), TCSetAttr (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )
                23.12.113            TCFlow

    Synopsis:    Terminal control:  Suspend transmission of data

Declaration:     function  TCFlow(fd:  LongInt;act:  LongInt)  :  Boolean

    Visibility:   default

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:    TCDrain (1062   ), TCFlush (1062   ), TCGetAttr (1063   ), TCGetPGrp (1063   ), TCSendBreak
                (1064   ), TCSetAttr (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )
                                                                                1062

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.114            TCFlush

    Synopsis:    Terminal control:  Discard data buffer

Declaration:     function  TCFlush(fd:  LongInt;qsel:  LongInt)  :  Boolean

    Visibility:   default

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 buffer

                TCOFLUSH            output buffer

                TCIOFLUSH             both input and output buffers


                The function returns True if the call was succesfull, False otherwise.

       Errors:   Errors are reported in LinuxError.

    See also:    TCDrain  (1062   ),  TCFlow  (1062   ),  TCGetAttr  (1063   ),  TCGetPGrp  (1063   ),  TCSendBreak
                (1064   ), TCSetAttr (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )
                23.12.115            TCGetAttr

    Synopsis:    Terminal Control:  Get terminal attributes

Declaration:     function  TCGetAttr(fd:  LongInt;var  tios:  Termios)  :  Boolean

    Visibility:   default

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:    TCDrain  (1062   ),  TCFlow  (1062   ),  TCFlush  (1062   ),  TCGetPGrp  (1063   ),  TCSendBreak
                (1064   ), TCSetAttr (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )


                Listing:  ./olinuxex/ex55.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 5;


                 u s e s o l d l i n u x;


                {   Program       t o  d e m o n s t r a t et h e  T C G e t A t t r/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
                    WriteLn     ( ' I n p u t F l a g s    :  $ ' ,h e x s t r( t 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 t r( t i 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



                                                                                1063

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                    WriteLn     ( ' Old    a t t r i b u t e:s' ) ;
                    T C G e t A t t r( 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 lmode    ') ;
                    CFMakeRaw       ( t i o s) ;
                    T C S e t A t t r( 1T,CSANOW     , t i o s) ;
                    WriteLn     ( ' C u r r e n t a t t r i b u t e:s' ) ;
                    T C G e t A t t r( 1 ,t i o s) ;
                    ShowTermios        ( t i o s) ;
                    T C S e t A t t r( 1T,CSANOW     , o l d i o s) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.116            TCGetPGrp

    Synopsis:    Terminal control:  Get process group

Declaration:     function  TCGetPGrp(fd:  LongInt;var  id:  LongInt)  :  Boolean

    Visibility:   default

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:    TCDrain (1062   ), TCFlow (1062   ), TCFlush (1062   ), TCGetAttr (1063   ), TCSendBreak (1064   ),
                TCSetAttr (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )
                23.12.117            TCSendBreak

    Synopsis:    Terminal control:  Send break

Declaration:     function  TCSendBreak(fd:  LongInt;duration:  LongInt)  :  Boolean

    Visibility:   default

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:    TCDrain (1062   ), TCFlow (1062   ), TCFlush (1062   ), TCGetAttr (1063   ), TCGetPGrp (1063   ),
                TCSetAttr (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )
                23.12.118            TCSetAttr

    Synopsis:    Terminal control:  Set attributes

Declaration:     function  TCSetAttr(fd:  LongInt;OptAct:  LongInt;const  tios:  Termios)
                                                :  Boolean

    Visibility:   default
                                                                                1064

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
Description:     TCSetAttr  sets  the  terminal  parameters  you  specify  in  a  TermIOS  structureTios  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.

                TCSAFLUSH            wait for output and discard all input not yet read.


                The function Returns True if the call was succesfull, False otherwise.

                For an example, see TCGetAttr (1063   ).

       Errors:   Errors are reported in LinuxError.

    See also:    TCDrain (1062   ), TCFlow (1062   ), TCFlush (1062   ), TCGetAttr (1063   ), TCGetPGrp (1063   ),
                TCSendBreak (1064   ), TCSetPGrp (1065   ), TTYName (1065   ), IsATTY (1035   )
                23.12.119            TCSetPGrp

    Synopsis:    Terminal control:  Set process group

Declaration:     function  TCSetPGrp(fd:  LongInt;id:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCSetPGrp  Sets  the  Process  Group  Id  to  Id.   The  function  returns  True  if  the  call  was
                successful, False otherwise.

                For an example, see TCGetPGrp (1063   ).

       Errors:   Errors are returned in LinuxError.

    See also:    TCDrain (1062   ), TCFlow (1062   ), TCFlush (1062   ), TCGetAttr (1063   ), TCGetPGrp (1063   ),
                TCSendBreak (1064   ), TCSetAttr (1064   ), TTYName (1065   ), IsATTY (1035   )
                23.12.120            TellDir

    Synopsis:    Return current location in a directory

Declaration:     function  TellDir(p:  PDir)  :  LongInt

    Visibility:   default

Description:     TellDir returns the current location in the directory structure pointed to by p.  It returns
                -1 on failure.

                For an example, see OpenDir (1043   ).

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1003   ), ReadDir (1046   ), SeekDir (1048   ), OpenDir (1043   )


                                                                                1065

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.121            TTYname

    Synopsis:    Terminal control:  Get terminal name

Declaration:     function  TTYname(Handle:  LongInt)  :  String
                function  TTYname(var  F:  Text)  :  String

    Visibility:   default

Description:     TTYNameReturns 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:    TCDrain (1062   ), TCFlow (1062   ), TCFlush (1062   ), TCGetAttr (1063   ), TCGetPGrp (1063   ),
                TCSendBreak (1064   ), TCSetAttr (1064   ), TCSetPGrp (1065   ), IsATTY (1035   ), IOCtl (1034   )
                23.12.122            Umask

    Synopsis:    Set file creation mask.

Declaration:     function  Umask(Mask:  Integer)  :  Integer

    Visibility:   default

Description:     Change the file creation mask for the current user to Mask.  The current mask is returned.

    See also:    Chmod (999  )


                Listing:__./olinuxex/ex27.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 7;


                {   Program       t o  d e m o n s t r a t et h e  Umask      f u n c t i o n. }


                Uses     o l d 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 l( 1 1 1 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                23.12.123            Uname

    Synopsis:    Return system name.

Declaration:     function  Uname(var  unamerec:  utsname)  :  Boolean

    Visibility:   default

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 (1029   ), GetDomainName (1025   )



                                                                                1066

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.124            UnLink

    Synopsis:    Unlink (i.e.  remove) a file.

Declaration:     function  UnLink(Path:  PathStr)  :  Boolean
                function  UnLink(Path:  pchar)  :  Boolean

    Visibility:   default

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.

                For an example, see Link (1036   ).

       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 effec-
                       tive 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 (1036   ), SymLink (1057   )
                23.12.125            Utime

    Synopsis:    Set access and modification times of a file (touch).

Declaration:     function  Utime(const  path:  PathStr;utim:  UTimeBuf)  :  Boolean

    Visibility:   default

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 (1027   ), Chown (1000   ), Access (993  )


                Listing:  ./olinuxex/ex25.pp


                                                                                1067

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   Program       t o  d e m o n s t r a t et h e  UTime      f u n c t i o n. }


                Uses     o l d l i n u x;


                Var     u t i m :   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 e s o u r c e}
                    GetTime       ( h o u r,m i n u t e, s e c o n d) ;
                    G e t D a t e ( y e a r,month    , day  ) ;
                    u t i m. 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) ;
                    u t i m. modtime     := u t i m .a c t i m e;
                    i f  not    Utime    ( 'e x 2 5 .pp  ' ,u t i m)   then
                        w r i t e l n(  'C a l l  t o  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 nt i m e s t o  :   ') ;
                       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___.____________________________________________________________________________________________________________*
 *___________

                23.12.126            WaitPid

    Synopsis:    Wait for a process to terminate

Declaration:     function  WaitPid(Pid:  LongInt;Status:  pointer;Options:  LongInt)
                                            :  LongInt

    Visibility:   default

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.

                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 hasexited.

                WUNTRACED                Causes WaitPid to return also for children which are stopped, but whose
                       status has not yet been reported.

                ____WCLONE         Causes WaitPid also to wait for threads created by the Clone (1001   ) call.

                Upon return, it returns the exit status of the process, or -1 in case of failure.

                For an example, see Fork (1020   ).

       Errors:   Errors are returned in LinuxError.

    See also:    Fork (1020   ), Execve (1011   )



                                                                                1068

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.127            WaitProcess

    Synopsis:    Wait for process to terminate.

Declaration:     function  WaitProcess(Pid:  LongInt)  :  LongInt

    Visibility:   default

Description:     WaitProcess  waits  for  process  PID  to  exit.   WaitProcess  is  equivalent  to  the  WaitPID
                (1068   ) call:


                WaitPid(PID,@result,0)


                Handles of Signal interrupts (errno=EINTR), and returns the Exitcode of Process PID (>=0)
                or -Status if it was terminated

       Errors:   None.

    See also:    WaitPID  (1068   ),  WTERMSIG  (1070   ),  WSTOPSIG  (1070   ),  WIFEXITED  (1069   ),  WIF-
                STOPPED (1070   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), W_STOPCODE (1071   ),
                WEXITSTATUS (1069   )
                23.12.128            WEXITSTATUS

    Synopsis:    Extract the exit status from the WaitPID (1068   ) result.

Declaration:     function  WEXITSTATUS(Status:  Integer)  :  Integer

    Visibility:   default

Description:     WEXITSTATUS can be used to extract the exit status from Status, the result of the WaitPID
                (1068   ) call.

    See also:    WaitPID (1068   ), WaitProcess (1068   ), WTERMSIG (1070   ), WSTOPSIG (1070   ), WIFEX-
                ITED (1069   ), WIFSTOPPED (1070   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), W_STOPCODE
                (1071   )
                23.12.129            WIFEXITED

    Synopsis:    Check whether the process exited normally

Declaration:     function  WIFEXITED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFEXITED checks Status and returns True if the status indicates that the process termi-
                nated normally, i.e.  was not stopped by a signal.

    See also:    WaitPID  (1068   ),  WaitProcess  (1068   ),  WTERMSIG  (1070   ),  WSTOPSIG  (1070   ),  WIF-
                STOPPED (1070   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), W_STOPCODE (1071   ),
                WEXITSTATUS (1069   )


                                                                                1069

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.130            WIFSIGNALED

    Synopsis:    Check whether the process was exited by a signal.

Declaration:     function  WIFSIGNALED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFSIGNALED returns True if Status indicates that the process exited because it received a
                signal.

    See also:    WaitPID (1068   ), WaitProcess (1068   ), WTERMSIG (1070   ), WSTOPSIG (1070   ), WIFEX-
                ITED (1069   ), WIFSTOPPED (1070   ), W_EXITCODE (1070   ), W_STOPCODE (1071   ), WEX-
                ITSTATUS (1069   )
                23.12.131            WIFSTOPPED

    Synopsis:    Check whether the process is currently stopped.

Declaration:     function  WIFSTOPPED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFSTOPPED  checks  Status  and  returns  true  if  the  process  is  currently  stopped.  This  is
                only possible if WUNTRACED was specified in the options of WaitPID (1068   ).

    See also:    WaitPID (1068   ), WaitProcess (1068   ), WTERMSIG (1070   ), WSTOPSIG (1070   ), WIFEX-
                ITED (1069   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), W_STOPCODE (1071   ), WEX-
                ITSTATUS (1069   )
                23.12.132            WSTOPSIG

    Synopsis:    Return the exit code from the process.

Declaration:     function  WSTOPSIG(Status:  Integer)  :  Integer

    Visibility:   default

Description:     WSTOPSIG is an alias for WEXITSTATUS (1069   ).

    See also:    WaitPID  (1068   ),  WaitProcess  (1068   ),  WTERMSIG  (1070   ),  WIFEXITED  (1069   ),  WIF-
                STOPPED (1070   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), W_STOPCODE (1071   ),
                WEXITSTATUS (1069   )
                23.12.133            WTERMSIG

    Synopsis:    Return the signal that caused a process to exit.

Declaration:     function  WTERMSIG(Status:  Integer)  :  Integer

    Visibility:   default

Description:     WTERMSIG extracts from Status the signal number which caused the process to exit.

    See also:    WaitPID  (1068   ),  WaitProcess  (1068   ),  WSTOPSIG  (1070   ),  WIFEXITED  (1069   ),  WIF-
                STOPPED (1070   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), W_STOPCODE (1071   ),
                WEXITSTATUS (1069   )

                                                                                1070

                ______________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________
                23.12.134            W__EXITCODE

    Synopsis:    Construct an exit status based on an return code and signal.

Declaration:     function  W_EXITCODE(ReturnCode:  Integer;Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_EXITCODE combines ReturnCode and Signal to a status code fit for WaitPid.

    See also:    WaitPID (1068   ), WaitProcess (1068   ), WTERMSIG (1070   ), WSTOPSIG (1070   ), WIFEX-
                ITED (1069   ), WIFSTOPPED (1070   ), WIFSIGNALED (1069   ), W_STOPCODE (1071   ), WEX-
                ITSTATUS (1069   )
                23.12.135            W__STOPCODE

    Synopsis:    Construct an exit status based on a signal.

Declaration:     function  W_STOPCODE(Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_STOPCODE constructs an exit status based on Signal, which will cause WIFSIGNALED
                (1069   ) to return True

    See also:    WaitPID (1068   ), WaitProcess (1068   ), WTERMSIG (1070   ), WSTOPSIG (1070   ), WIFEX-
                ITED (1069   ), WIFSTOPPED (1070   ), WIFSIGNALED (1069   ), W_EXITCODE (1070   ), WEX-
                ITSTATUS (1069   )

                                                                                1071


Chapter   24


Reference   for   unit   'ports'
24.1          Overview


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).

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.
24.2          Constants,  types  and  variables



24.2.1         Variables

port  :  tport


Default instance of type TPort (1073   ).  Do not free.  This variable is initialized in the unit
initialization code, and freed at finalization.

Since there is a default property for a variable of this type, a sentence as


port[221]:=12;


Will result in the integer 12 being written to port 221, if port is defined as a variable of type
tport


portb  :  tport


Default instance of type TPort (1073   ).  Do not free.  This variable is initialized in the unit
initialization code, and freed at finalization.

Since there is a default property for a variable of this type, a sentence as


portb[221]:=12;


Will result in the byte 12 being written to port 221, if port is defined as a variable of type
tport



                                                            1072

                ____________________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'PORTS'_______________*
 *___________________
                portl  :  tportl


                Default instance of type TPortL (1073   ).  Do not free.  This variable is initialized in the unit
                initialization code, and freed at finalization.

                Since there is a default property for a variable of this type, a sentence as


                portl[221]:=12;


                Will result in the longint 12 being written to port 221, if port is defined as a variable of type
                tport


                portw  :  tportw


                Default instance of type TPortW (1074   ).  Do not free.  This variable is initialized in the unit
                initialization code, and freed at finalization.

                Since there is a default property for a variable of this type, a sentence as


                portw[221]:=12;


                Will result in the word 12 being written to port 221, if port is defined as a variable of type
                tport
                24.3          tport



                24.3.1         Description

                The TPort type is implemented specially for access to the ports in a TP compatible manner.
                There is no need to create an instance of this type:  the standard TP variables are instantiated
                at unit initialization.
                24.3.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1073______pp______________rw___________Access_integer-sized_port_by_port_number__________________________________*
 *___________
                24.3.3         tport.pp

    Synopsis:    Access integer-sized port by port number

Declaration:     Property  pp[w:  LongInt]:  Byte;  default

    Visibility:   public

      Access:    Read,Write

Description:     Access integer-sized port by port number
                24.4          tportl



                24.4.1         Description

                The TPortL type is implemented specially for access to the ports in a TP compatible manner.
                There is no need to create an instance of this type:  the standard TP variables are instantiated
                at unit initialization.



                                                                                1073

                ____________________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'PORTS'_______________*
 *___________________
                24.4.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1074______pp______________rw___________Access_Longint-sized_port_by_port_number__________________________________*
 *___________
                24.4.3         tportl.pp

    Synopsis:    Access Longint-sized port by port number

Declaration:     Property  pp[w:  LongInt]:  LongInt;  default

    Visibility:   public

      Access:    Read,Write

Description:     Access Longint-sized port by port number
                24.5          tportw



                24.5.1         Description

                The TPortW type is implemented specially for access to the ports in a TP compatible manner.
                There is no need to create an instance of this type:  the standard TP variables are instantiated
                at unit initialization.
                24.5.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1074______pp______________rw___________Access_word-sized_port_by_port_number_____________________________________*
 *___________
                24.5.3         tportw.pp

    Synopsis:    Access word-sized port by port number

Declaration:     Property  pp[w:  LongInt]:  Word;  default

    Visibility:   public

      Access:    Read,Write

Description:     Access word-sized port by port number



                                                                                1074


                Chapter   25


                Reference   for   unit   'printer'
                25.1          Overview


                This chapter describes the PRINTER unit for Free Pascal.  It was written for dos by Florian
                Klaempfl,  and  it  was  written  for  linux  by  Michael  Van  Canneyt,  and  has  been  ported  to
                Windows  and  os/2  as  well.   Its  basic  functionality  is  the  same  for  al  supported  systems,
                although there are minor differences on linux/unix.
                25.2          Constants,  types  and  variables



                25.2.1         Variables

                Lst  :  text


                Lst is the standard printing device.
                On linux, Lst is set up using AssignLst('/tmp/PID.lst').
                25.3          Procedures  and  functions



                25.3.1         AssignLst

    Synopsis:    Assign text file to printing device

Declaration:     procedure  AssignLst(var  F:  text;ToFile:  String)

    Visibility:   default

Description:     AssignLst Assigns to F a printing device - Unix only.  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)



                                                                            1075

                ________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'PRINTER'_________________*
 *___________________
    See also:    lst (1075   )


                Listing:  ./printex/printex.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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 ru n i t ') ;
                    w r i t e l n ( ' W r i t i n gt o   l s t. . .' ) ;
                    f o r  i : = 1  t o  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 U n i x}
                    w r i t e l n ( ' W r i t i n gt o   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  t o  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___.____________________________________________________________________________________________________________*
 *___________

                25.3.2         InitPrinter

    Synopsis:    Initialize the printer

Declaration:     procedure  InitPrinter(const  PrinterName:  String)

    Visibility:   default

Description:     Initialize the printer
                25.3.3         IsLstAvailable

    Synopsis:    Determine whether printer is available.

Declaration:     function  IsLstAvailable  :  Boolean

    Visibility:   default

Description:     Determine whether printer is available.

                                                                                1076


Chapter   26


Reference   for   unit   'Sockets'
26.1          Used  units
                                    Table 26.1:  Used units by unit 'Sockets'


                                                 __Name______________Page____
                                                   baseunix          1077
                                                   UnixType          1077



26.2          Overview


This  document  describes  the  SOCKETS  unit  for  Free  Pascal.  it  was  written  for  linux  by
Michael Van Canneyt, and ported to Windows by Florian Klaempfl.
26.3          Constants,  types  and  variables



26.3.1         Constants

AF_APPLETALK  =  5


Address family Appletalk DDP


AF_ASH  =  18


Address family:  Ash


AF_ATMPVC  =  8


Address family:  ATM PVCs


AF_ATMSVC  =  20


Address family:  ATM SVCs



                                                            1077

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
AF_AX25  =  3


Address family Amateur Radio AX.25


AF_BLUETOOTH  =  31


Address family:  Bluetooth sockets


AF_BRIDGE  =  7


Address family Multiprotocol bridge


AF_DECnet  =  12


Address family:  Reserved for DECnet project.


AF_ECONET  =  19


Address family:  Acorn Econet


AF_INET  =  2


Address family Internet IP Protocol


AF_INET6  =  10


Address family IP version 6


AF_IPX  =  4


Address family Novell IPX


AF_IRDA  =  23


Address family:  IRDA sockets


AF_KEY  =  15


Address family:  PF_KEY key management API


AF_LLC  =  26


Address family:  Linux LLC


AF_LOCAL  =  1


Address family:  Unix socket


AF_MAX  =  32


Address family Maximum value



                                                                1078

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
AF_NETBEUI  =  13


Address family:  Reserved for 802.2LLC project


AF_NETLINK  =  16


Address family:  ?


AF_NETROM  =  6


Address family Amateur radio NetROM


AF_PACKET  =  17


Address family:  Packet family


AF_PPPOX  =  24


Address family:  PPPoX sockets


AF_ROSE  =  11


Address family:  Amateur Radio X.25 PLP


AF_ROUTE  =  AF_NETLINK


Address family:  Alias to emulate 4.4BSD.


AF_SECURITY  =  14


Address family:  Security callback pseudo AF


AF_SNA  =  22


Addresss family:  Linux SNA project


AF_TIPC  =  30


Address family:  TIPC sockets


AF_UNIX  =  1


Address family Unix domain sockets


AF_UNSPEC  =  0


Address family Not specified


AF_WANPIPE  =  25


Address family:  Wanpipe API Sockets



                                                                1079

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
AF_X25  =  9


Address family Reserved for X.25 project


EsockEACCESS  =  ESysEAcces


Access forbidden error


EsockEBADF  =  EsysEBADF


Alias:  bad file descriptor


EsockEFAULT  =  EsysEFAULT


Alias:  an error occurred


EsockEINTR  =  EsysEINTR


Alias :  operation interrupted


EsockEINVAL  =  EsysEINVAL


Alias:  Invalid value specified


EsockEMFILE  =  ESysEmfile


Error code ?


EsockEMSGSIZE  =  ESysEMsgSize


Wrong message size error


EsockENOBUFS  =  ESysENoBufs


No buffer space available error


EsockENOTCONN  =  ESysENotConn


Not connected error


EsockENOTSOCK  =  ESysENotSock


File descriptor is not a socket error


EsockEPROTONOSUPPORT  =  ESysEProtoNoSupport


Protocol not supported error


EsockEWOULDBLOCK  =  ESysEWouldBlock


Operation would block error



                                                                1080

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
INADDR_ANY  =  CARDINAL  (  0  )


Undocumented ?


INADDR_NONE  =  CARDINAL  (  $FFFFFFFF  )


Undocumented ?


IPPROTO_AH  =  51


authentication header.


IPPROTO_COMP  =  108


Compression Header Protocol.


IPPROTO_DSTOPTS  =  60


IPv6 destination options.


IPPROTO_EGP  =  8


Exterior Gateway Protocol.


IPPROTO_ENCAP  =  98


Encapsulation Header.


IPPROTO_ESP  =  50


encapsulating security payload.


IPPROTO_FRAGMENT  =  44


IPv6 fragmentation header.


IPPROTO_GRE  =  47


General Routing Encapsulation.


IPPROTO_HOPOPTS  =  0


IPv6 Hop-by-Hop options.


IPPROTO_ICMP  =  1


Internet Control Message Protocol.


IPPROTO_ICMPV6  =  58


ICMPv6.



                                                                1081

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IPPROTO_IDP  =  22


XNS IDP protocol.


IPPROTO_IGMP  =  2


Internet Group Management Protocol.


IPPROTO_IP  =  0


Dummy protocol for TCP.


IPPROTO_IPIP  =  4


IPIP tunnels (older KA9Q tunnels use 94).


IPPROTO_IPV6  =  41


IPv6 header.


IPPROTO_MAX  =  255


Maximum value for IPPROTO options


IPPROTO_MTP  =  92


Multicast Transport Protocol.


IPPROTO_NONE  =  59


IPv6 no next header.


IPPROTO_PIM  =  103


Protocol Independent Multicast.


IPPROTO_PUP  =  12


PUP protocol.


IPPROTO_RAW  =  255


Raw IP packets.


IPPROTO_ROUTING  =  43


IPv6 routing header.


IPPROTO_RSVP  =  46


Reservation Protocol.



                                                                1082

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IPPROTO_SCTP  =  132


Stream Control Transmission Protocol.


IPPROTO_TCP  =  6


Transmission Control Protocol.


IPPROTO_TP  =  29


SO Transport Protocol Class 4.


IPPROTO_UDP  =  17


User Datagram Protocol.


IPV6_ADDRFORM  =  1


Undocumented Getsockopt option ?


IPV6_ADD_MEMBERSHIP  =  IPV6_JOIN_GROUP


Undocumented Getsockopt option ?


IPV6_AUTHHDR  =  10


Undocumented Getsockopt option ?


IPV6_CHECKSUM  =  7


Undocumented Getsockopt option ?


IPV6_DROP_MEMBERSHIP  =  IPV6_LEAVE_GROUP


Undocumented Getsockopt option ?


IPV6_DSTOPTS  =  4


Undocumented Getsockopt option ?


IPV6_HOPLIMIT  =  8


Undocumented Getsockopt option ?


IPV6_HOPOPTS  =  3


Undocumented Getsockopt option ?


IPV6_IPSEC_POLICY  =  34


Undocumented Getsockopt option ?



                                                                1083

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IPV6_JOIN_ANYCAST  =  27


Undocumented Getsockopt option ?


IPV6_JOIN_GROUP  =  20


Undocumented Getsockopt option ?


IPV6_LEAVE_ANYCAST  =  28


Undocumented Getsockopt option ?


IPV6_LEAVE_GROUP  =  21


Undocumented Getsockopt option ?


IPV6_MTU  =  24


Undocumented Getsockopt option ?


IPV6_MTU_DISCOVER  =  23


Undocumented Getsockopt option ?


IPV6_MULTICAST_HOPS  =  18


Undocumented Getsockopt option ?


IPV6_MULTICAST_IF  =  17


Undocumented Getsockopt option ?


IPV6_MULTICAST_LOOP  =  19


Undocumented Getsockopt option ?


IPV6_NEXTHOP  =  9


Undocumented Getsockopt option ?


IPV6_PKTINFO  =  2


Undocumented Getsockopt option ?


IPV6_PKTOPTIONS  =  6


Undocumented Getsockopt option ?


IPV6_PMTUDISC_DO  =  2


Always DF.



                                                                1084

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IPV6_PMTUDISC_DONT  =  0


Never send DF frames.


IPV6_PMTUDISC_WANT  =  1


Use per route hints.


IPV6_RECVERR  =  25


Undocumented Getsockopt option ?


IPV6_ROUTER_ALERT  =  22


Undocumented Getsockopt option ?


IPV6_RTHDR  =  5


Undocumented Getsockopt option ?


IPV6_RTHDR_LOOSE  =  0


Hop doesn't need to be neighbour.


IPV6_RTHDR_STRICT  =  1


Hop must be a neighbour.


IPV6_RTHDR_TYPE_0  =  0


IPv6 Routing header type 0.


IPV6_RXDSTOPTS  =  IPV6_DSTOPTS


Undocumented Getsockopt option ?


IPV6_RXHOPOPTS  =  IPV6_HOPOPTS


Undocumented Getsockopt option ?


IPV6_RXSRCRT  =  IPV6_RTHDR


Undocumented Getsockopt option ?


IPV6_UNICAST_HOPS  =  16


Undocumented Getsockopt option ?


IPV6_V6ONLY  =  26


Undocumented Getsockopt option ?



                                                                1085

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IPV6_XFRM_POLICY  =  35


Undocumented Getsockopt option ?


IP_ADD_MEMBERSHIP  =  35


add an IP group membership


IP_ADD_SOURCE_MEMBERSHIP  =  39


join source group


IP_BLOCK_SOURCE  =  38


block data from source


IP_DEFAULT_MULTICAST_LOOP  =  1


Undocumented ?


IP_DEFAULT_MULTICAST_TTL  =  1


Undocumented ?


IP_DROP_MEMBERSHIP  =  36


drop an IP group membership


IP_DROP_SOURCE_MEMBERSHIP  =  40


leave source group


IP_HDRINCL  =  3


Header is included with data.


IP_MAX_MEMBERSHIPS  =  20


Undocumented ?


IP_MSFILTER  =  41


Undocumented ?


IP_MTU_DISCOVER  =  10


Undocumented ?


IP_MULTICAST_IF  =  32


set/get IP multicast i/f



                                                                1086

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IP_MULTICAST_LOOP  =  34


set/get IP multicast loopback


IP_MULTICAST_TTL  =  33


set/get IP multicast ttl


IP_OPTIONS  =  4


IP per-packet options.


IP_PKTINFO  =  8


Undocumented ?


IP_PKTOPTIONS  =  9


Undocumented ?


IP_PMTUDISC  =  10


Undocumented ?


IP_PMTUDISC_DO  =  2


Always DF.


IP_PMTUDISC_DONT  =  0


Never send DF frames.


IP_PMTUDISC_WANT  =  1


Use per route hints.


IP_RECVERR  =  11


Undocumented ?


IP_RECVOPTS  =  6


Receive all IP options w/datagram.


IP_RECVRETOPTS  =  IP_RETOPTS


Receive IP options for response.


IP_RECVTOS  =  13


Undocumented ?



                                                                1087

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
IP_RECVTTL  =  12


Undocumented ?


IP_RETOPTS  =  7


Set/get IP per-packet options.


IP_ROUTER_ALERT  =  5


Undocumented ?


IP_TOS  =  1


IP type of service and precedence.


IP_TTL  =  2


IP time to live.


IP_UNBLOCK_SOURCE  =  37


unblock data from source


MCAST_BLOCK_SOURCE  =  43


block from given group


MCAST_EXCLUDE  =  0


Undocumented ?


MCAST_INCLUDE  =  1


Undocumented ?


MCAST_JOIN_GROUP  =  42


join any-source group


MCAST_JOIN_SOURCE_GROUP  =  46


join source-spec gruoup


MCAST_LEAVE_GROUP  =  45


leave any-source group


MCAST_LEAVE_SOURCE_GROUP  =  47


leave source-spec group



                                                                1088

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
MCAST_MSFILTER  =  48


Undocumented ?


MCAST_UNBLOCK_SOURCE  =  44


unblock from given group


MSG_CONFIRM  =  $0800


Send flags:  Conform connection


MSG_CTRUNC  =  $0008


Receive flags:  Control Data was discarded (buffer too small)


MSG_DONTROUTE  =  $0004


Send flags:  don't use gateway


MSG_DONTWAIT  =  $0040


Receive flags:  Non-blocking operation request.


MSG_EOF  =  MSG_FIN


Alias for MSG_FIN


MSG_EOR  =  $0080


Receive flags:  End of record


MSG_ERRQUERE  =  $2000


Receive flags:  ?


MSG_FIN  =  $0200


Receive flags:  ?


MSG_MORE  =  $8000


Receive flags:  ?


MSG_NOSIGNAL  =  $4000


Receive flags:  Suppress SIG_PIPE signal.


MSG_OOB  =  $0001


Receive flags:  receive out-of-band data.



                                                                1089

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
MSG_PEEK  =  $0002


Receive flags:  peek at data, don't remove from buffer.


MSG_PROXY  =  $0010


Receive flags:  ?


MSG_RST  =  $1000


Receive flags:  ?


MSG_SYN  =  $0400


Receive flags:  ?


MSG_TRUNC  =  $0020


Receive flags:  packet Data was discarded (buffer too small)


MSG_TRYHARD  =  MSG_DONTROUTE


Receive flags:  ?


MSG_WAITALL  =  $0100


Receive flags:  Wait till operation completed.


NoAddress  :  in_addr  =  (s_addr:0  )


Constant indicating invalid (no) network address.


NoAddress6  :  in6_addr  =  (u6_addr16:  (  0,0,0,0,0,0,0,0  )  )


Constant indicating invalid (no) IPV6 network address.


NoNet  :  in_addr  =  (s_addr:0  )


Constant indicating invalid (no) network address.


NoNet6  :  in6_addr  =  (u6_addr16:  (  0,0,0,0,0,0,0,0  )  )


Constant indicating invalid (no) IPV6 network address.


PF_APPLETALK  =  AF_APPLETALK


Protocol family:  Appletalk DDP


PF_ASH  =  AF_ASH


Protocol family:  Ash



                                                                1090

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
PF_ATMPVC  =  AF_ATMPVC


Protocol family:  ATM PVCs


PF_ATMSVC  =  AF_ATMSVC


Protocol family:  ATM SVCs


PF_AX25  =  AF_AX25


Protocol family:  Amateur Radio AX.25


PF_BLUETOOTH  =  AF_BLUETOOTH


Protocol family:  Bluetooth sockets


PF_BRIDGE  =  AF_BRIDGE


Protocol family:  Multiprotocol bridge


PF_DECnet  =  AF_DECnet


Protocol Family:  DECNET project


PF_ECONET  =  AF_ECONET


Protocol family:  Acorn Econet


PF_INET  =  AF_INET


Protocol family:  Internet IP Protocol


PF_INET6  =  AF_INET6


Protocol family:  IP version 6


PF_IPX  =  AF_IPX


Protocol family:  Novell IPX


PF_IRDA  =  AF_IRDA


Protocol family:  IRDA sockets


PF_KEY  =  AF_KEY


Protocol family:  Key management API


PF_LLC  =  AF_LLC


Protocol family:  Linux LLC



                                                                1091

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
PF_LOCAL  =  AF_LOCAL


Protocol family:  Unix socket


PF_MAX  =  AF_MAX


Protocol family:  Maximum value


PF_NETBEUI  =  AF_NETBEUI


Protocol family:  Reserved for 802.2LLC project


PF_NETLINK  =  AF_NETLINK


Protocol family:  ?


PF_NETROM  =  AF_NETROM


Protocol family:Amateur radio NetROM


PF_PACKET  =  AF_PACKET


Protocol family:  Packet family


PF_PPPOX  =  AF_PPPOX


Protocol family:  PPPoX sockets


PF_ROSE  =  AF_ROSE


Protocol family:  Amateur Radio X.25 PLP


PF_ROUTE  =  AF_ROUTE


Protocol Family:  ?


PF_SECURITY  =  AF_SECURITY


Protocol family:  Security callback pseudo PF


PF_SNA  =  AF_SNA


Protocol Family:  Linux SNA project


PF_TIPC  =  AF_TIPC


Protocol family:  TIPC sockets


PF_UNIX  =  AF_UNIX


Protocol family:  Unix domain sockets



                                                                1092

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
PF_UNSPEC  =  AF_UNSPEC


Protocol family:  Unspecified


PF_WANPIPE  =  AF_WANPIPE


Protocol family:  Wanpipe API Sockets


PF_X25  =  AF_X25


Protocol family:  Reserved for X.25 project


SCM_SRCRT  =  IPV6_RXSRCRT


Undocumented Getsockopt option ?


SCM_TIMESTAMP  =  SO_TIMESTAMP


Socket option:  ?


SHUT_RD  =  0


Shutdown read part of full duplex socket


SHUT_RDWR  =  2


Shutdown read and write part of full duplex socket


SHUT_WR  =  1


Shutdown write part of full duplex socket


SOCK_DGRAM  =  2


Type of socket:  datagram (conn.less) socket (UDP)


SOCK_MAXADDRLEN  =  255


Maximum socket address length for Bind (1101   ) call.


SOCK_RAW  =  3


Type of socket:  raw socket


SOCK_RDM  =  4


Type of socket:  reliably-delivered message


SOCK_SEQPACKET  =  5


Type of socket:  sequential packet socket



                                                                1093

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
SOCK_STREAM  =  1


Type of socket:  stream (connection) type socket (TCP)


SOL_ICMPV6  =  58


Socket level values for IPv6:  ICMPV6


SOL_IP  =  0


Undocumented ?


SOL_IPV6  =  41


Socket level values for IPv6:  IPV6


SOL_SOCKET  =  1


Socket option level:  Socket level


SOMAXCONN  =  128


Maximum queue length specifiable by listen.


SO_ACCEPTCONN  =  30


Socket option:  ?


SO_ATTACH_FILTER  =  26


Socket option:  ?


SO_BINDTODEVICE  =  25


Socket option:  ?


SO_BROADCAST  =  6


Socket option:  Broadcast


SO_BSDCOMPAT  =  14


Socket option:  ?


SO_DEBUG  =  1


Socket option level:  debug


SO_DETACH_FILTER  =  27


Socket option:  ?



                                                                1094

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
SO_DONTROUTE  =  5


Socket option:  Don't route


SO_ERROR  =  4


Socket option:  Error


SO_KEEPALIVE  =  9


Socket option:  keep alive


SO_LINGER  =  13


Socket option:  ?


SO_NO_CHECK  =  11


Socket option:  ?


SO_OOBINLINE  =  10


Socket option:  ?


SO_PASSCRED  =  16


Socket option:  ?


SO_PEERCRED  =  17


Socket option:  ?


SO_PEERNAME  =  28


Socket option:  ?


SO_PRIORITY  =  12


Socket option:  ?


SO_RCVBUF  =  8


Socket option:  receive buffer


SO_RCVLOWAT  =  18


Socket option:  ?


SO_RCVTIMEO  =  20


Socket option:  ?



                                                                1095

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
SO_REUSEADDR  =  2


Socket option:  Reuse address


SO_SECURITY_AUTHENTICATION  =  22


Socket option:  ?


SO_SECURITY_ENCRYPTION_NETWORK  =  24


Socket option:  ?


SO_SECURITY_ENCRYPTION_TRANSPORT  =  23


Socket option:  ?


SO_SNDBUF  =  7


Socket option:  Send buffer


SO_SNDLOWAT  =  19


Socket option:  ?


SO_SNDTIMEO  =  21


Socket option:  ?


SO_TIMESTAMP  =  29


Socket option:  ?


SO_TYPE  =  3


Socket option:  Type


S_IN  =  0


Input socket in socket pair.


S_OUT  =  1


Output socket in socket pair
26.3.2         Types

in6_addr  =  packed  record
end
Record used to describe a general IPV6 address.



                                                                1096

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
in_addr  =  packed  record
end
General inet socket address.


linger  =  packed  record
   l_onoff  :  cint;
   l_linger  :  cint;
end
This record is used in the setsockopt (1077   ) call to specify linger options.


PIn6Addr  =  pin6_addr


Pointer to in6_addr (1096   ) type.


pin6_addr  =  ^in6_addr


Pointer to Tin6_addr (1098   )


PInAddr  =  pin_addr


Alias for pin_addr (1097   )


PInetSockAddr  =  psockaddr_in


Pointer to sockaddr_in (1098   )


PInetSockAddr6  =  psockaddr_in6


Pointer to sockaddr_in6 (1098   ) type


pin_addr  =  ^in_addr


Pointer to in_addr (1097   ) record.


plinger  =  ^linger


Pointer to linger (1097   ) type.


psockaddr  =  ^sockaddr


Pointer to TSockAddr (1099   )


psockaddr_in  =  ^sockaddr_in


Pointer to sockaddr_in (1098   )


psockaddr_in6  =  ^sockaddr_in6



                                                                1097

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
Pointer to sockaddr_in6 (1098   )


psockaddr_un  =  ^sockaddr_un


Pointer to sockaddr_un (1098   ) type.


sa_family_t  =  cushort


Address family type


sockaddr  =  packed  record
end
sockaddr is used to store a general socket addres for the Bind (1101   ), Recv (1117   ) and Send
(1118   ) calls.


sockaddr_in  =  packed  record
end
sockaddr_in is used to store a INET socket addres for the Bind (1101   ),  Recv (1117   ) and
Send (1118   ) calls.


sockaddr_in6  =  packed  record
   sin6_family  :  sa_family_t;
   sin6_port  :  cuint16;
   sin6_flowinfo  :  cuint32;
   sin6_addr  :  in6_addr;
   sin6_scope_id  :  cuint32;
end
Alias for sockaddr_in6 (1098   )


sockaddr_un  =  packed  record
   sun_family  :  sa_family_t;
   sun_path  :  Array[0..107]  of  Char;
end
sockaddr_un is used to store a UNIX socket addres for the Bind (1101   ),  Recv (1117   ) and
Send (1118   ) calls.


TIn6Addr  =  in6_addr


Alias for in6_addr (1096   ) type.


Tin6_addr  =  in6_addr


Alias for sockaddr_in6 (1098   )



                                                                1098

            ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_____________________*
 *_______________
            TInAddr  =  in_addr


            Alias for in_addr (1097   ) record type.


            TInetSockAddr  =  sockaddr_in


            Alias for sockaddr_in (1098   )


            TInetSockAddr6  =  sockaddr_in6


            Alias for sockaddr_in6 (1098   )


            TIn_addr  =  in_addr


            Alias for in_addr (1097   ) record type.


            TLinger  =  linger


            Alias for linger (1077   )


            TSockAddr  =  sockaddr
            TSockArray  =  Array[1..2]  of  LongInt


            Type returned by the SocketPair (1121   ) call.


            Tsocket  =  LongInt


            Alias for easy kylix porting


            TSockPairArray  =  Array[0..1]  of  LongInt


            Array of sockets, used in SocketPair (1121   ) call.


            TUnixSockAddr  =  packed  record
               family  :  sa_family_t;
               path  :  Array[0..107]  of  Char;
            end
            Alias for sockaddr_un (1098   )
            26.4          Procedures  and  functions



            26.4.1         Accept

Synopsis:    Accept a connection from a socket (deprecated).


                                                                            1099

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
Declaration:     function  Accept(Sock:  LongInt;var  Addr;var  Addrlen:  LongInt)  :  LongInt
                function  Accept(Sock:  LongInt;var  addr:  TInetSockAddr;var  SockIn:  File;
                                        var  SockOut:  File)  :  Boolean
                function  Accept(Sock:  LongInt;var  addr:  TInetSockAddr;var  SockIn:  text;
                                        var  SockOut:  text)  :  Boolean
                function  Accept(Sock:  LongInt;var  addr:  String;var  SockIn:  text;
                                        var  SockOut:  text)  :  Boolean
                function  Accept(Sock:  LongInt;var  addr:  String;var  SockIn:  File;
                                        var  SockOut:  File)  :  Boolean

    Visibility:  default

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.

                The alternate forms of the Accept (1099   ) command, with the Text or File parameters are
                equivalent  to  subsequently  calling  the  regular  Accept  (1099   )  function  and  the  Sock2Text
                (1120   ) or Sock2File (1120   ) functions.  These functions return True if successful, False oth-
                erwise.

       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.

                SYS__EWOULDBLOCK                     The requested operation would block the process.


    See also:    Listen (1115   ), Connect (1102   ), Bind (1101   )


                Listing:  ./sockex/socksvr.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program        s e r v e r;


                {
                    Program       t o  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 r t o   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  t o  c o n n e c t t o  t h a t  s o c k e t
                }


                 u s e s S o c k e t s;


                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  , S o u t  :  T e x t;
                    SAddr           :  T I n e t S o c k A d d;r


                 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) ;



                                                                                1100

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                    h a l t( 1 0 0 ) ;
                end   ;

                 b e g i n
                    S := S o c k e t ( AF _INET     ,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  :  ' ) ;
                    SAddr    . s i n _f a m i l y:=AF _INET     ;
                    {   p o r t 5 0 0 0 0  i n  n e t w o r k o r d e r }
                    SAddr    . s i n _p o r t:= h t o n s( 5 0 0 0 0 ) ;
                    SAddr    . s i n _a d d r.s _a d d r : = 0 ;
                    i f  not    B i n d( S ,SAddr    , s i z e o f(s a d d r) )  then
                      P E r r o r ( ' S e r v e r :  B i n d  :   ') ;
                    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 f r o m C l i e n t,  r u n  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   ,S o u t)   then
                      P E r r o r ( ' S e r v e r :  A c c e p t  :  '+ fromname      ) ;
                    R e s e t(S i n ) ;
                    ReWrite     ( S o u t) ;
                    W r i t e l n(Sout   , 'M e s s a g e 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  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                26.4.2         Bind

    Synopsis:    Bind a socket to an address (deprecated).

Declaration:     function  Bind(Sock:  LongInt;const  Addr;AddrLen:  LongInt)  :  Boolean
                function  Bind(Sock:  LongInt;const  addr:  String)  :  Boolean

    Visibility:   default

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.

                The form of the Bind command with the TUnixSockAddr (1099   ) is equivalent to subsequently
                calling Str2UnixSockAddr (1121   ) and the regular Bind function.  The function returns True
                if successfull, False otherwise.

       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 (1120   )

                                                                                1101

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.3         CloseSocket

    Synopsis:    Closes a socket handle.

Declaration:     function  CloseSocket(Sock:  LongInt)  :  LongInt

    Visibility:   default

Description:     CloseSocket closes a socket handle.  It returns 0 if the socket was closed succesfully, -1 if
                it failed.

       Errors:   On error, -1 is returned.

    See also:    Socket (1120   )
                26.4.4         Connect

    Synopsis:    Open a connection to a server socket (deprecated).

Declaration:     function  Connect(Sock:  LongInt;const  Addr;Addrlen:  LongInt)  :  Boolean
                function  Connect(Sock:  LongInt;const  addr:  TInetSockAddr;
                                           var  SockIn:  text;var  SockOut:  text)  :  Boolean
                function  Connect(Sock:  LongInt;const  addr:  TInetSockAddr;
                                           var  SockIn:  File;var  SockOut:  File)  :  Boolean
                function  Connect(Sock:  LongInt;const  addr:  String;var  SockIn:  text;
                                           var  SockOut:  text)  :  Boolean
                function  Connect(Sock:  LongInt;const  addr:  String;var  SockIn:  File;
                                           var  SockOut:  File)  :  Boolean

    Visibility:   default

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 forms of the Connect (1102   ) command with the Text or File arguments are equivalent
                to subsequently calling the regular Connect function and the Sock2Text (1120   ) or Sock2File
                (1120   ) functions.  These functions return True if successfull, False otherwise.

                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 (1115   ), Bind (1101   ), Accept (1099   )


                Listing:  ./sockex/sockcli.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program        C l i e n t;


                {
                    Program       t o  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 r t o   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  t o  c o n n e c t t o  t h a t  s o c k e t
                }


                 u s e s S o c k e t s;


                 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;



                                                                                1102

________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___
    h a l t( 1 0 0 ) ;
end   ;



Var
    SAddr           :  T I n e t S o c k A d d;r
    B u f f e r     :  s t r i n g [ 2 5 5 ] ;
    S               :  L o n g i n t;
    Sin  , S o u t  :  T e x t;
    i               :  i n t e g e r;


 b e g i n
    S := S o c k e t ( AF _INET     ,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 i n _f a m i l y:=AF _INET     ;
    {   p o r t 5 0 0 0 0  i n  n e t w o r k o r d e r }
    SAddr    . s i n _p o r t:= h t o n s( 5 0 0 0 0 ) ;
    {   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 }
    SAddr    . s i n _a d d r.s _a d d r:=  HostToNet       ( ( 1 2 7 s h l  2 4 )  o r  1 ) ;
    i f  not    C o n n e c t ( S ,SAddr    , Sin  , S o u t)  then
      P E r r o r(' C l i e n t :  C o n n e c t  :  ' ) ;
    R e s e t(S i n ) ;
    ReWrite     ( S o u t) ;
    B u f f e r:= ' T h i s  i s  a  t e x t s t r i n gs e n t  by   t h e  C l i e n t. ';
    f o r  i : = 1  t o  1 0  do
      W r i t e l n(Sout   , B u f f e r) ;
    F l u s h(S o u t ) ;
    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___._______________________________________________________________________________________________________________________


Listing:__./sockex/pfinger.pp_________________________________________________________________________________________________

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  , S o u t  :  T e x t;
    L i n e  :  s t r i n g;


 b e g i n
    Addr   . s i n _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   . s i n _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   . s i n _a d d r. s _a d d r: = ( ( 1 s h l  2 4 )  o r  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(  'C o u l d n'' t  c o n n e c t t o   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 r(S 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) ;



                                                                1103

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                    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___.____________________________________________________________________________________________________________*
 *___________

                26.4.5         fpaccept

    Synopsis:    Accept a connection from a socket.

Declaration:     function  fpaccept(s:  cint;addrx:  psockaddr;addrlen:  psocklen)  :  cint

    Visibility:   default

Description:     Accept  accepts  a  connection  from  a  socket  S,  which  was  listening  for  a  connection.   If
                a  connection  is  accepted,  a  file  descriptor  is  returned  (positive  number).   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  Addrx,  and  sets  its  length  in
                Addrlen.   Addrx  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.

                SYS__EWOULDBLOCK                      The requested operation would block the process.


    See also:    fpListen (1109   ), fpConnect (1106   ), fpBind (1105   )


                Listing:  ./sockex/socksvr.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program        s e r v e r;


                {
                    Program       t o  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 r t o   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  t o  c o n n e c t t o  t h a t  s o c k e t
                }


                 u s e s S o c k e t s;


                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;



                                                                                1104

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                    Sin  , S o u t  :  T e x t;
                    SAddr           :  T I n e t S o c k A d d;r


                 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 _INET     ,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  :  ' ) ;
                    SAddr    . s i n _f a m i l y:=AF _INET     ;
                    {   p o r t 5 0 0 0 0  i n  n e t w o r k o r d e r }
                    SAddr    . s i n _p o r t:= h t o n s( 5 0 0 0 0 ) ;
                    SAddr    . s i n _a d d r.s _a d d r : = 0 ;
                    i f  not    B i n d( S ,SAddr    , s i z e o f(s a d d r) )  then
                      P E r r o r ( ' S e r v e r :  B i n d  :   ') ;
                    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 f r o m C l i e n t,  r u n  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   ,S o u t)   then
                      P E r r o r ( ' S e r v e r :  A c c e p t  :  '+ fromname      ) ;
                    R e s e t(S i n ) ;
                    ReWrite     ( S o u t) ;
                    W r i t e l n(Sout   , 'M e s s a g e 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  ;
                end___.____________________________________________________________________________________________________________*
 *___________

                26.4.6         fpbind

    Synopsis:    Bind a socket to an address.

Declaration:     function  fpbind(s:  cint;addrx:  psockaddr;addrlen:  tsocklen)  :  cint

    Visibility:   default

Description:     fpBind  binds  the  socket  s  to  address  Addrx.   Addrx  has  length  Addrlen.   The  function
                returns 0 if the call was succesful, -1 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 (1120   )



                                                                                1105

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.7         fpconnect

    Synopsis:    Open a connection to a server socket.

Declaration:     function  fpconnect(s:  cint;name:  psockaddr;namelen:  tsocklen)  :  cint

    Visibility:   default

Description:     fpConnect  opens  a  connection  to  a  peer,  whose  address  is  described  by  Name.   NameLen
                contains  the  length  of  the  address.  The  type  of  Name  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:    fpListen (1109   ), fpBind (1105   ), fpAccept (1104   )


                Listing:  ./sockex/sockcli.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program        C l i e n t;


                {
                    Program       t o  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 r t o   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  t o  c o n n e c t t o  t h a t  s o c k e t
                }


                 u s e s S o c k e t s;


                 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           :  T I n e t S o c k A d d;r
                    B u f f e r     :  s t r i n g [ 2 5 5 ] ;
                    S               :  L o n g i n t;
                    Sin  , S o u t  :  T e x t;
                    i               :  i n t e g e r;


                 b e g i n
                    S := S o c k e t ( AF _INET     ,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 i n _f a m i l y:=AF _INET     ;
                    {   p o r t 5 0 0 0 0  i n  n e t w o r k o r d e r }
                    SAddr    . s i n _p o r t:= h t o n s( 5 0 0 0 0 ) ;
                    {   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 }
                    SAddr    . s i n _a d d r.s _a d d r:=  HostToNet       ( ( 1 2 7 s h l  2 4 )  o r  1 ) ;
                    i f  not    C o n n e c t ( S ,SAddr    , Sin  , S o u t)  then
                      P E r r o r(' C l i e n t :  C o n n e c t  :  ' ) ;
                    R e s e t(S i n ) ;
                    ReWrite     ( S o u t) ;
                    B u f f e r:= ' T h i s  i s  a  t e x t s t r i n gs e n t  by   t h e  C l i e n t. ';
                    f o r  i : = 1  t o  1 0  do
                      W r i t e l n(Sout   , B u f f e r) ;
                                                                                1106

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                    F l u s h(S o u t ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________


                Listing:__./sockex/pfinger.pp______________________________________________________________________________________*
 *___________

                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  , S o u t  :  T e x t;
                    L i n e  :  s t r i n g;


                 b e g i n
                    Addr   . s i n _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   . s i n _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   . s i n _a d d r. s _a d d r: = ( ( 1 s h l  2 4 )  o r  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(  'C o u l d n'' t  c o n n e c t t o   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 r(S 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___.____________________________________________________________________________________________________________*
 *___________

                26.4.8         fpgetpeername

    Synopsis:    Return the name (address) of the connected peer.

Declaration:     function  fpgetpeername(s:  cint;name:  psockaddr;namelen:  psocklen)  :  cint

    Visibility:   default

Description:     fpGetPeerName  returns  the  name  of  the  entity  connected  to  the  specified  socket  S.  The
                Socket must be connected for this call to work.

                Name should point to enough space to store the name, the amount of space pointed to should
                be set in Namelen.  When the function returns succesfully, Name will be filled with the name,
                and Name will be set to the length of  Name.



                                                                                1107

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
       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:    fpConnect (1106   ), fpSocket (1112   )
                26.4.9         fpgetsockname

    Synopsis:    Return name of socket.

Declaration:     function  fpgetsockname(s:  cint;name:  psockaddr;namelen:  psocklen)  :  cint

    Visibility:   default

Description:     fpGetSockName  returns  the  current  name  of  the  specified  socket  S.  Name  should  point  to
                enough space to store the name, the amount of space pointed to should be set in Namelen.
                When the function returns succesfully, Name will be filled with the name, and Namelen will
                be set to the length of  Name.

       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:    fpBind (1105   )
                26.4.10          fpgetsockopt

    Synopsis:    Get current socket options

Declaration:     function  fpgetsockopt(s:  cint;level:  cint;optname:  cint;optval:  pointer;
                                                   optlen:  psocklen)  :  cint

    Visibility:   default

Description:     fpGetSockOpt gets the connection option optname, for socket S. 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  interpret  the
                       option.


                The options are stored in the memory location pointed to by optval.  optlen should point
                to the initial length of  optval,  and on return will contain the actual length of the stored
                data.

                On success, 0 is returned.  On Error, -1 is returned.

       Errors:   Errors are reported in SocketError, and include the following:



                                                                                1108

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                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:    fpSetSockOpt (1111   )
                26.4.11          fplisten

    Synopsis:    Listen for connections on a socket.

Declaration:     function  fplisten(s:  cint;backlog:  cint)  :  cint

    Visibility:   default

Description:     fpListen listens for up to backlog connections from socket S. The socket S must be of type
                SOCK_STREAM or Sock_SEQPACKET.

                The function returns 0 if a connection was accepted, -1 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:    fpSocket (1112   ), fpBind (1105   ), fpConnect (1106   )
                26.4.12          fprecv

    Synopsis:    Receive data on socket

Declaration:     function  fprecv(s:  cint;buf:  pointer;len:  size_t;flags:  cint)  :  ssize_t

    Visibility:   default

Description:     fpRecv reads at most len bytes from socket S into address buf.  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 (1118   )



                                                                                1109

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.13          fprecvfrom

    Synopsis:    Receive data from an unconnected socket

Declaration:     function  fprecvfrom(s:  cint;buf:  pointer;len:  size_t;flags:  cint;
                                                from:  psockaddr;fromlen:  psocklen)  :  ssize_t

    Visibility:   default

Description:     fpRecvFrom receives data in buffer Buf with maximum length Len from socket S. Receipt
                is controlled by options in Flags.  The location pointed to by  from will be filled with the
                address from the sender, and it's length will be stored in fromlen.  The function returns the
                number of bytes received, or -1 on error.  AddrLen.

       Errors:   On error, -1 is returned.

    See also:    fpSocket (1112   ), fprecv (1109   )
                26.4.14          fpsend

    Synopsis:    Send data through socket

Declaration:     function  fpsend(s:  cint;msg:  pointer;len:  size_t;flags:  cint)  :  ssize_t

    Visibility:   default

Description:     fpSend  sends  Len  bytes  starting  from  address  Msg  to  socket  S.  S  must  be  in  a  connected
                state.  Options can be passed in Flags.

                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:    fpRecv (1109   )
                26.4.15          fpsendto

    Synopsis:    Send data through an unconnected socket to an address.

Declaration:     function  fpsendto(s:  cint;msg:  pointer;len:  size_t;flags:  cint;
                                            tox:  psockaddr;tolen:  tsocklen)  :  ssize_t

    Visibility:   default

Description:     fpSendTo sends data from buffer Msg with length len through socket S with options Flags.
                The data is sent to address tox, which has length toLen

       Errors:   On error, -1 is returned.

    See also:    fpSocket (1112   ), fpSend (1110   ), fpRecvFrom (1110   )



                                                                                1110

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.16          fpsetsockopt

    Synopsis:    Set socket options.

Declaration:     function  fpsetsockopt(s:  cint;level:  cint;optname:  cint;optval:  pointer;
                                                   optlen:  tsocklen)  :  cint

    Visibility:   default

Description:     fpSetSockOpt sets the connection options for socket S. The socket may be manipulated 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.


                The actual option is stored in a buffer pointed to by optval, with length optlen.

                For more information on this call, refer to the unix manual page setsockopt

       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:    fpGetSockOpt (1108   )
                26.4.17          fpshutdown

    Synopsis:    Close one end of full duplex connection.

Declaration:     function  fpshutdown(s:  cint;how:  cint)  :  cint

    Visibility:   default

Description:     fpShutDown closes one end of a full duplex socket connection, described by S. The parameter
                How determines 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:    fpSocket (1112   ), fpConnect (1106   )



                                                                                1111

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.18          fpsocket

    Synopsis:    Create new socket

Declaration:     function  fpsocket(domain:  cint;xtype:  cint;protocol:  cint)  :  cint

    Visibility:   default

Description:     fpSocket creates a new socket in domain Domain, from type xType 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  fpBind  (1105   )  call.   If  unsuccesfull,  the
                function returns -1.

                for an example, see Accept (1099   ).

       Errors:   Errors are returned in SocketError, and include the follwing:


                SYS__EPROTONOSUPPORT                           The protocol type or the specified protocol is not supported
                       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 de-
                       nied.

                SYS__ENOBUFS              Insufficient buffer space is available.  The socket cannot be created until
                       sufficient resources are freed.


    See also:    SocketPair (1121   )
                26.4.19          fpsocketpair

    Synopsis:    Create socket pair.

Declaration:     function  fpsocketpair(d:  cint;xtype:  cint;protocol:  cint;sv:  pcint)
                                                     :  cint

    Visibility:   default

Description:     fpSocketPair creates 2 sockets in domain D, from type xType and using protocol Protocol.
                The  pair  is  returned  in  sv,  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 (1120   )

    See also:    Str2UnixSockAddr (1121   )
                26.4.20          GetPeerName

    Synopsis:    Return the name (address) of the connected peer (deprecated).

Declaration:     function  GetPeerName(Sock:  LongInt;var  Addr;var  Addrlen:  LongInt)
                                                   :  LongInt

    Visibility:   default
                                                                                1112

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
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 (1102   ), Socket (1120   )
                26.4.21          GetSocketName

    Synopsis:    Return name of socket (deprecated).

Declaration:     function  GetSocketName(Sock:  LongInt;var  Addr;var  Addrlen:  LongInt)
                                                      :  LongInt

    Visibility:   default

Description:     GetSocketName 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.
                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 (1101   )
                26.4.22          GetSocketOptions

    Synopsis:    Get current socket options (deprecated).

Declaration:     function  GetSocketOptions(Sock:  LongInt;Level:  LongInt;OptName:  LongInt;
                                                         var  OptVal;var  optlen:  LongInt)  :  LongInt

    Visibility:   default

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.



                                                                                1113

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                For more information on this call, refer to the unix manual page \seem{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:    SetSocketOptions (1118   )
                26.4.23          HostAddrToStr

    Synopsis:    Convert a host address to a string.

Declaration:     function  HostAddrToStr(Entry:  in_addr)  :  AnsiString

    Visibility:   default

Description:     HostAddrToStr  converts  the  host  address  in  Entry  to  a  string  representation  in  human-
                readable form (a dotted quad).

                Basically, it is the same as NetAddrToStr (1115   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1115   ), StrToHostAddr (1122   ), StrToNetAddr (1122   )
                26.4.24          HostAddrToStr6

    Synopsis:    Convert a IPV6 host address to a string representation.

Declaration:     function  HostAddrToStr6(Entry:  Tin6_addr)  :  AnsiString

    Visibility:   default

Description:     HostAddrToStr6  converts  the  IPV6  host  address  in  Entry  to  a  string  representation  in
                human-readable form.

                Basically, it is the same as NetAddrToStr6 (1116   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1115   ), StrToHostAddr (1122   ), StrToNetAddr (1122   ), StrToHostAddr6 (1122   )
                26.4.25          HostToNet

    Synopsis:    Convert a host address to a network address

Declaration:     function  HostToNet(Host:  in_addr)  :  in_addr
                function  HostToNet(Host:  LongInt)  :  LongInt

    Visibility:   default

Description:     HostToNet converts a host address to a network address.  It takes care of endianness of the
                host machine.  The address can be specified as a dotted quad or as a longint.

       Errors:   None.

    See also:    NetToHost (1116   ), NToHS (1116   ), HToNS (1115   ), ShortHostToNet (1119   ), ShortNetToHost
                (1119   )



                                                                                1114

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.26          htonl

    Synopsis:    Convert long integer from host ordered to network ordered

Declaration:     function  htonl(host:  LongInt)  :  LongInt

    Visibility:   default

Description:     htonl makes sure that the bytes in host are ordered in the correct way for sending over the
                network and returns the correctly ordered result.

    See also:    htons (1115   ), ntohl (1116   ), ntohs (1116   )
                26.4.27          htons

    Synopsis:    Convert short integer from host ordered to network ordered

Declaration:     function  htons(host:  Word)  :  Word

    Visibility:   default

Description:     htons makes sure that the bytes in host are ordered in the correct way for sending over the
                network and returns the correctly ordered result.

    See also:    htonl (1115   ), ntohl (1116   ), ntohs (1116   )
                26.4.28          Listen

    Synopsis:    Listen for connections on socket (deprecated).

Declaration:     function  Listen(Sock:  LongInt;MaxConnect:  LongInt)  :  Boolean

    Visibility:   default

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 (1120   ), Bind (1101   ), Connect (1102   )
                26.4.29          NetAddrToStr

    Synopsis:    Convert a network address to a string.

Declaration:     function  NetAddrToStr(Entry:  in_addr)  :  AnsiString

    Visibility:   default

Description:     NetAddrToStr converts the network address in Entry to a string representation in human-
                readable form (a dotted quad).

    See also:    HostAddrToStr (1114   ), StrToNetAddr (1122   ), StrToHostAddr (1122   )



                                                                                1115

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.30          NetAddrToStr6

    Synopsis:    Convert a IPV6 network address to a string.

Declaration:     function  NetAddrToStr6(Entry:  Tin6_addr)  :  AnsiString

    Visibility:   default

Description:     NetAddrToStr6 converts the IPV6 network address in Entry to a string representation in
                human-readable form.

                Basically, it is the same as NetAddrToStr6 (1116   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1115   ), StrToHostAddr (1122   ), StrToNetAddr (1122   ), StrToHostAddr6 (1122   )
                26.4.31          NetToHost

    Synopsis:    Convert a network address to a host address.

Declaration:     function  NetToHost(Net:  in_addr)  :  in_addr
                function  NetToHost(Net:  LongInt)  :  LongInt

    Visibility:   default

Description:     NetToHost converts a network address to a host address.  It takes care of endianness of the
                host machine.  The address can be specified as a dotted quad or as a longint.

       Errors:   None.

    See also:    HostToNet (1114   ), NToHS (1116   ), HToNS (1115   ), ShortHostToNet (1119   ), ShortNetToHost
                (1119   )
                26.4.32          NToHl

    Synopsis:    Convert long integer from network ordered to host ordered

Declaration:     function  NToHl(Net:  LongInt)  :  LongInt

    Visibility:   default

Description:     ntohs  makes  sure  that  the  bytes  in  Net,  received  from  the  network,  are  ordered  in  the
                correct way for handling by the host machinen, and returns the correctly ordered result.

    See also:    htonl (1115   ), htons (1115   ), ntohs (1116   )
                26.4.33          NToHs

    Synopsis:    Convert short integer from network ordered to host ordered

Declaration:     function  NToHs(Net:  Word)  :  Word

    Visibility:   default

Description:     ntohs  makes  sure  that  the  bytes  in  Net,  received  from  the  network,  are  ordered  in  the
                correct way for handling by the host machinen, and returns the correctly ordered result.

    See also:    htonl (1115   ), htons (1115   ), ntohl (1116   )



                                                                                1116

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.34          Recv

    Synopsis:    Receive data on socket (deprecated)

Declaration:     function  Recv(Sock:  LongInt;var  Buf;BufLen:  LongInt;Flags:  LongInt)
                                       :  LongInt

    Visibility:   default

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 (1118   )
                26.4.35          RecvFrom

    Synopsis:    Receive data from an unconnected socket (deprecated)

Declaration:     function  RecvFrom(Sock:  LongInt;var  Buf;Buflen:  LongInt;Flags:  LongInt;
                                            var  Addr;var  AddrLen:  LongInt)  :  LongInt

    Visibility:   default

Description:     RecvFrom receives data in buffer Buf with maximum length BufLen from socket Sock.  Re-
                ceipt is controlled by options in Flags.  Addr will be filled with the address from the sender,
                and  will  have  length  The  function  returns  the  number  of  bytes  received,  or  -1  on  error.
                AddrLen.

       Errors:   On error, -1 is returned.

    See also:    Socket (1120   ), recv (1117   ), Send (1118   )



                                                                                1117

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.36          Send

    Synopsis:    Send data through socket (deprecated)

Declaration:     function  Send(Sock:  LongInt;const  Buf;BufLen:  LongInt;Flags:  LongInt)
                                       :  LongInt

    Visibility:   default

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 (1117   )
                26.4.37          SendTo

    Synopsis:    Send data through an unconnected socket to an address (deprecated).

Declaration:     function  SendTo(Sock:  LongInt;const  Buf;BufLen:  LongInt;Flags:  LongInt;
                                         var  Addr;AddrLen:  LongInt)  :  LongInt

    Visibility:   default

Description:     SendTo sends data from buffer Buf with length Buflen through socket Sock with options
                Flags.  The data is sent to address Addr, which has length AddrLen

       Errors:   On error, -1 is returned.

    See also:    Socket (1120   ), Send (1118   ), RecvFrom (1117   )
                26.4.38          SetSocketOptions

    Synopsis:    Set socket options (deprecated).

Declaration:     function  SetSocketOptions(Sock:  LongInt;Level:  LongInt;OptName:  LongInt;
                                                         const  OptVal;optlen:  LongInt)  :  LongInt

    Visibility:   default

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:
                                                                                1118

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                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

       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 (1113   )
                26.4.39          ShortHostToNet

    Synopsis:    Convert a host port number to a network port number

Declaration:     function  ShortHostToNet(Host:  Word)  :  Word

    Visibility:   default

Description:     ShortHostToNet converts a host port number to a network port number.  It takes care of
                endianness of the host machine.

       Errors:   None.

    See also:    ShortNetToHost (1119   ), HostToNet (1114   ), NToHS (1116   ), HToNS (1115   )
                26.4.40          ShortNetToHost

    Synopsis:    Convert a network port number to a host port number

Declaration:     function  ShortNetToHost(Net:  Word)  :  Word

    Visibility:   default

Description:     ShortNetToHost converts a network port number to a host port number.  It takes care of
                endianness of the host machine.

       Errors:   None.

    See also:    ShortNetToHost (1119   ), HostToNet (1114   ), NToHS (1116   ), HToNS (1115   )
                26.4.41          Shutdown

    Synopsis:    Close one end of full duplex connection (deprecated).

Declaration:     function  Shutdown(Sock:  LongInt;How:  LongInt)  :  LongInt

    Visibility:   default

Description:     fpShutDown  closes  one  end  of  a  full  duplex  socket  connection,  described  by  Sock.   The
                parameter  How  determines  how  the  connection  will  be  shut  down,  and  can  be  one  of  the
                following:


                0 Further receives are disallowed.



                                                                                1119

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                1Further sends are disallowed.

                2Sending 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 (1120   ), Connect (1102   )
                26.4.42          Sock2File

    Synopsis:    Convert socket to untyped file descriptors

Declaration:     procedure  Sock2File(Sock:  LongInt;var  SockIn:  File;var  SockOut:  File)

    Visibility:   default

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 (1120   ), Sock2Text (1120   )
                26.4.43          Sock2Text

    Synopsis:    Convert socket to text file descriptors

Declaration:     procedure  Sock2Text(Sock:  LongInt;var  SockIn:  Text;var  SockOut:  Text)

    Visibility:   default

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 (1120   ), Sock2File (1120   )
                26.4.44          Socket

    Synopsis:    Create new socket (deprecated)

Declaration:     function  Socket(Domain:  LongInt;SocketType:  LongInt;Protocol:  LongInt)
                                           :  LongInt

    Visibility:   default

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  con-
                stants (see the section on constants for available constants) If succesfull, the function returns
                a socket descriptor, which can be passed to a subsequent Bind (1101   ) call.  If unsuccesfull,
                the function returns -1.

                for an example, see Accept (1099   ).



                                                                                1120

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
       Errors:   Errors are returned in SocketError, and include the follwing:


                SYS__EPROTONOSUPPORT                          The protocol type or the specified protocol is not supported
                      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 de-
                      nied.

                SYS__ENOBUFS             Insufficient buffer space is available.  The socket cannot be created until
                      sufficient resources are freed.


    See also:    SocketPair (1121   )
                26.4.45          socketerror

    Synopsis:    Contains the error code for the last socket operation.

Declaration:     function  socketerror  :  cint

    Visibility:   default

Description:     SocketError contains the error code for the last socket operation.  It can be examined to
                return the last socket error.
                26.4.46          SocketPair

    Synopsis:    Create socket pair (deprecated).

Declaration:     function  SocketPair(Domain:  LongInt;SocketType:  LongInt;
                                                Protocol:  LongInt;var  Pair:  TSockArray)  :  LongInt

    Visibility:   default

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 (1120   )

    See also:    Str2UnixSockAddr (1121   )
                26.4.47          Str2UnixSockAddr

    Synopsis:    Convert path to TUnixSockAddr (1099   )

Declaration:     procedure  Str2UnixSockAddr(const  addr:  String;var  t:  TUnixSockAddr;
                                                           var  len:  LongInt)

    Visibility:   default

Description:     Str2UnixSockAddr transforms a Unix socket address in a string to a TUnixSockAddr struc-
                ture which can be passed to the Bind (1101   ) call.

       Errors:   None.

    See also:    Socket (1120   ), Bind (1101   )



                                                                                1121

                ________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________
                26.4.48          StrToHostAddr

    Synopsis:    Convert a string to a host address.

Declaration:     function  StrToHostAddr(IP:  AnsiString)  :  in_addr

    Visibility:   default

Description:     StrToHostAddr converts the string representation in IP to a host address and returns the
                host address.

       Errors:   On error, the host address is filled with zeroes.

    See also:    NetAddrToStr (1115   ), HostAddrToStr (1114   ), StrToNetAddr (1122   )
                26.4.49          StrToHostAddr6

    Synopsis:    Convert a string to a IPV6 host address.

Declaration:     function  StrToHostAddr6(IP:  String)  :  Tin6_addr

    Visibility:   default

Description:     StrToHostAddr6 converts the string representation in IP to a IPV6 host address and returns
                the host address.

       Errors:   On error, the address is filled with zeroes.

    See also:    NetAddrToStr6 (1116   ), HostAddrToStr6 (1114   ), StrToHostAddr (1122   )
                26.4.50          StrToNetAddr

    Synopsis:    Convert a string to a network address.

Declaration:     function  StrToNetAddr(IP:  AnsiString)  :  in_addr

    Visibility:   default

Description:     StrToNetAddr  converts  the  string  representation  in  IP  to  a  network  address  and  returns
                the network address.

       Errors:   On error, the network address is filled with zeroes.

    See also:    NetAddrToStr (1115   ), HostAddrToStr (1114   ), StrToHostAddr (1122   )
                26.4.51          StrToNetAddr6

    Synopsis:    Convert a string to a IPV6 network address

Declaration:     function  StrToNetAddr6(IP:  AnsiString)  :  Tin6_addr

    Visibility:   default

Description:     StrToNetAddr6  converts  the  string  representation  in  IP  to  a  IPV6  network  address  and
                returns the network address.

       Errors:   On error, the address is filled with zeroes.

    See also:    NetAddrToStr6 (1116   ), HostAddrToStr6 (1114   ), StrToHostAddr6 (1122   )

                                                                                1122


                Chapter   27


                Reference   for   unit   'strings'
                27.1          Overview


                This chapter describes the STRINGS unit for Free Pascal.  This unit is system independent,
                and therefore works on all supported platforms.
                27.2          Procedures  and  functions



                27.2.1         stralloc

    Synopsis:    Allocate memory for a new null-terminated string on the heap

Declaration:     function  stralloc(L:  SizeInt)  :  pchar

    Visibility:   default

Description:     StrAlloc reserves memory on the heap for a string with length Len, terminating #0 included,
                and returns a pointer to it.

       Errors:   If there is not enough memory, a run-time error occurs.

    See also:    StrNew (1131   ), StrPCopy (1133   )
                27.2.2         strcat

    Synopsis:    Concatenate 2 null-terminated strings.

Declaration:     function  strcat(dest:  pchar;source:  pchar)  :  pchar

    Visibility:   default

Description:     Attaches Source to Dest and returns Dest.

       Errors:   No length checking is performed.

    See also:    StrLCat (1127   )


                Listing:  ./stringex/ex11.pp



                                                                            1123

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                Uses     s t r i n g s;


                {   Program       t o  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    ;


                 b e g i n
                    P2 :=  S t r A l l o c (S t r L e n(P1  ) * 2 + 1 ) ;
                    StrMove       (P2  , P1  ,S t r L e n(P1  ) + 1 ) ; {   P2 = P1   }
                    S t r C a t ( P2  ,P1  ) ;                          {   Append      P2   o n c e  more     }
                    W r i t e l n ( 'P2    :   ',P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.3         strcomp

    Synopsis:    Compare 2 null-terminated strings, case sensitive.

Declaration:     function  strcomp(str1:  pchar;str2:  pchar)  :  SizeInt

    Visibility:   default

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.


                For an example, see StrLComp (1128   ).

       Errors:   None.

    See also:    StrLComp (1128   ), StrIComp (1127   ), StrLIComp (1130   )
                27.2.4         strcopy

    Synopsis:    Copy a null-terminated string

Declaration:     function  strcopy(dest:  pchar;source:  pchar)  :  pchar

    Visibility:   default

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 (1133   ), StrLCopy (1129   ), StrECopy (1125   )


                Listing:  ./stringex/ex4.pp


                                                                                1124

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                Uses     s t r i n g s;


                {   Program       t o  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  :  PP =  ' ,PP  ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.5         strdispose

    Synopsis:    disposes of a null-terminated string on the heap

Declaration:     procedure  strdispose(p:  pchar)

    Visibility:   default

Description:     Removes the string in P from the heap and releases the memory.

       Errors:   None.

    See also:    StrNew (1131   )


                Listing:  ./stringex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                Uses     s t r i n g s;


                {   Program       t o  d e m o n s t r a t et h e  S t r D i s p o s ef 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  ) ;
                    W r i t e l n ( 'P2    :   ',P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.6         strecopy

    Synopsis:    Copy a null-terminated string, return a pointer to the end.
                                                                                1125

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
Declaration:     function  strecopy(dest:  pchar;source:  pchar)  :  pchar

    Visibility:  default

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 (1129   ), StrCopy (1124   )


                Listing:  ./stringex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                Uses     s t r i n g s;


                {   Program       t o  d e m o n s t r a t et h e  S t r E 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.' ;


                Var    PP    :  PChar    ;


                 b e g i n
                    PP :=  S t r A l l o c (S t r L e n(P ) + 1 ) ;
                    I f  L o n g i n t(StrECopy      ( PP  ,P )) - L o n g i n t(PP )<>   S t r L e n(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  ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.7         strend

    Synopsis:    Return a pointer to the end of a null-terminated string

Declaration:     function  strend(p:  pchar)  :  pchar

    Visibility:   default

Description:     Returns a pointer to the end of  P. (i.e.  to the terminating null-character.

       Errors:   None.

    See also:    StrLen (1129   )


                Listing:  ./stringex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                Uses     s t r i n g s;


                {   Program       t o  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 )<>  S t r L e n(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  ! ' )



                                                                                1126

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                    e l s e
                        W r i t e l n(  'A l l  i s  w e l l. . ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.8         stricomp

    Synopsis:    Compare 2 null-terminated strings, case insensitive.

Declaration:     function  stricomp(str1:  pchar;str2:  pchar)  :  SizeInt

    Visibility:   default

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 (1128   ), StrComp (1124   ), StrLIComp (1130   )


                Listing:  ./stringex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                Uses     s t r i n g s;


                {   Program       t o  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 ) ;
                    dec  ( l ) ;
                    W r i t e l n ( l , '  c h a r a c t e r sa r e  t h e  same   . ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.9         strlcat

    Synopsis:    Concatenate 2 null-terminated strings, with length boundary.

Declaration:     function  strlcat(dest:  pchar;source:  pchar;l:  SizeInt)  :  pchar

    Visibility:   default

Description:     Adds MaxLen characters from Source to Dest, and adds a terminating null-character.  Re-
                turns Dest.
                                                                                1127

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
       Errors:   None.

    See also:    StrCat (1123   )


                Listing:  ./stringex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;


                Uses     s t r i n g s;


                {   Program       t o  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 (S t r L e n(P1  ) * 2 + 1 ) ;
                    P2 ^ : = # 0 ;  {  Z e r o  l e n g t h }
                    S t r C a t ( P2  ,P1  ) ;
                    S t r L C a t (P2  , P1  , 5 ) ;
                    W r i t e l n ( 'P2   =    ',P2  ) ;
                    S t r D i s p o s(eP2  )
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.10          strlcomp

    Synopsis:    Compare limited number of characters of 2 null-terminated strings

Declaration:     function  strlcomp(str1:  pchar;str2:  pchar;l:  SizeInt)  :  SizeInt

    Visibility:   default

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 (1124   ), StrIComp (1127   ), StrLIComp (1130   )


                Listing:  ./stringex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                Uses     s t r i n g s;


                {   Program       t o  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



                                                                                1128

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                    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 sa r e  t h e  same   . ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.11          strlcopy

    Synopsis:    Copy a null-terminated string, limited in length.

Declaration:     function  strlcopy(dest:  pchar;source:  pchar;maxlen:  SizeInt)  :  pchar

    Visibility:   default

Description:     Copies MaxLen characters from Source to Dest, and makes Dest a null terminated string.

       Errors:   No length checking is performed.

    See also:    StrCopy (1124   ), StrECopy (1125   )


                Listing:  ./stringex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                Uses     s t r i n g s;


                {   Program       t o  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 1 0  c h a r a c t e r so f  P   :   ' ,StrLCopy        (PP  ,P  , 1 0 ) ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.12          strlen

    Synopsis:    Length of a null-terminated string.

Declaration:     function  strlen(p:  pchar)  :  sizeint

    Visibility:   default

Description:     Returns the length of the null-terminated string P.

       Errors:   None.

    See also:    StrNew (1131   )


                Listing:  ./stringex/ex1.pp
                                                                                1129

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                Uses     s t r i n g s;


                {   Program       t o  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.  }


                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 )  :   ', S t r L e n(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.13          strlicomp

    Synopsis:    Compare limited number of characters in 2 null-terminated strings, ignoring case.

Declaration:     function  strlicomp(str1:  pchar;str2:  pchar;l:  SizeInt)  :  SizeInt

    Visibility:   default

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.


                For an example, see StrIComp (1127   )

       Errors:   None.

    See also:    StrLComp (1128   ), StrComp (1124   ), StrIComp (1127   )
                27.2.14          strlower

    Synopsis:    Convert null-terminated string to all-lowercase.

Declaration:     function  strlower(p:  pchar)  :  pchar

    Visibility:   default

Description:     Converts P to an all-lowercase string.  Returns P.

       Errors:   None.

    See also:    StrUpper (1135   )


                Listing:  ./stringex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                Uses     s t r i n g s;


                {   Program       t o  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 }

                                                                                1130

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                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___.____________________________________________________________________________________________________________*
 *___________

                27.2.15          strmove

    Synopsis:    Move a null-terminated string to new location.

Declaration:     function  strmove(dest:  pchar;source:  pchar;l:  SizeInt)  :  pchar

    Visibility:   default

Description:     Copies  MaxLen  characters  from  Source  to  Dest.  No  terminating  null-character  is  copied.
                Returns Dest

       Errors:   None.

    See also:    StrLCopy (1129   ), StrCopy (1124   )


                Listing:  ./stringex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                Uses     s t r i n g s;


                {   Program       t o  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    :  P c h a r;


                 b e g i n
                    P2 :=  S t r A l l o c(S t r L e n(P1 ) + 1 ) ;
                    StrMove       (P2  , P1  ,S t r L e n(P1  ) + 1 ) ; {   P2 :=  P1   }
                    W r i t e l n ( 'P2   =    ',P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.16          strnew

    Synopsis:    Allocate room for new null-terminated string.

Declaration:     function  strnew(p:  pchar)  :  pchar

    Visibility:   default

Description:     Copies P to the Heap, and returns a pointer to the copy.

       Errors:   Returns Nil if no memory was available for the copy.
                                                                                1131

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
    See also:    StrCopy (1124   ), StrDispose (1125   )


                Listing:  ./stringex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                Uses     s t r i n g s;


                {   Program       t o  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  c a n' 't   be   h a p p e n i n g. . .')
                    e l s e
                        w r i t e l n(  'P2   :   ' ,P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.17          strpas

    Synopsis:    Convert a null-terminated string to a shortstring.

Declaration:     function  strpas(p:  pchar)  :  shortstring

    Visibility:   default

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 (1133   )


                Listing:  ./stringex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                Uses     s t r i n g s;


                {   Program       t o  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 := S t r P a s ( P ) ;
                    W r i t e l n ( 'S   :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1132

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                27.2.18          strpcopy

    Synopsis:    Copy a pascal string to a null-terminated string

Declaration:     function  strpcopy(d:  pchar;const  s:  String)  :  pchar

    Visibility:   default

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 (1132   )


                Listing:  ./stringex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;


                Uses     s t r i n g s;


                {   Program       t o  d e m o n s t r a t et h e  S t r P C o p y 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   :  P c h a r;


                 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 ) ;
                    S t r D i s p o s(eP ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.19          strpos

    Synopsis:    Search for a null-terminated substring in a null-terminated string

Declaration:     function  strpos(str1:  pchar;str2:  pchar)  :  pchar

    Visibility:   default

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:    StrScan (1134   ), StrRScan (1134   )


                Listing:  ./stringex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                Uses     s t r i n g s;


                {   Program       t o  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.  }

                                                                                1133

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                Const      P   :  PChar     =   ' T h i s  i s a   PChar      s t r i n g.' ;
                           S   :  P c h a r =   ' i s' ;
                 b e g i n
                    W r i t e l n ( ' P o s i t i o no f   '' i s ''   i n P   :   ' ,l o n g i n t(S t r P o s(P , S)) -  L o n g *
 *i n t(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                27.2.20          strrscan

    Synopsis:    Find last occurrence of a character in a null-terminated string.

Declaration:     function  strrscan(p:  pchar;c:  Char)  :  pchar

    Visibility:   default

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.

                For an example, see StrScan (1134   ).

       Errors:   None.

    See also:    StrScan (1134   ), StrPos (1133   )
                27.2.21          strscan

    Synopsis:    Find first occurrence of a character in a null-terminated string.

Declaration:     function  strscan(p:  pchar;c:  Char)  :  pchar

    Visibility:   default

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:    StrRScan (1134   ), StrPos (1133   )


                Listing:  ./stringex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;


                Uses     s t r i n g s;


                {   Program       t o  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 gf r o m  f i r s t  ' 's ' '  :   ' ,S t r S c a n(P ,s ) ) ;
                    W r i t e l n ( 'P ,   s t a r t i n gf r o m  l a s t  ' 's ' '  :   ' ,StrRScan      ( P ,s ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1134

                _________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________
                27.2.22          strupper

    Synopsis:    Convert null-terminated string to all-uppercase

Declaration:     function  strupper(p:  pchar)  :  pchar

    Visibility:   default

Description:     Converts P to an all-uppercase string.  Returns P.

                For an example, see StrLower (1130   )

       Errors:   None.

    See also:    StrLower (1130   )
                                                                                1135


Chapter   28


Reference   for   unit   'strutils'
28.1          Used  units
                                    Table 28.1:  Used units by unit 'strutils'


                                                  __Name___________Page_____
                                                    SysUtils       1136



28.2          Constants,  types  and  variables



28.2.1         Resource  strings

SErrAmountStrings  =  'Amount  of  search  and  replace  strings  don''t  match'


Error message used in stringsreplace function
28.2.2         Constants

AnsiResemblesProc  :  TCompareTextProc  =  @SoundexProc


This procedural variable is standard set to SoundexProc (1160   ) but can be overriden with a
user-defined algorithm.  This algorithm should return True if  AText resembles AOtherText,
or False otherwise.  The standard routine compares the soundexes of the two strings and
returns True if they are equal.


Brackets  =  ['(',')','[',']','{','}']


Set of characters that contain all possible bracket characters


DigitChars  =  ['0'..'9']


Set of digit characters


StdSwitchChars  =  ['-','/']



                                                            1136

_______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________________________*
 *___
Standard characters for the SwitchChars argument of GetCmdLineArg (1149   ).


StdWordDelims  =  [#0..'  ',',','.',';','/','\',':','''','"','`']  +  Brackets


Standard word delimiter values.


WordDelimiters  :  Set  of  Char  =  [#0..#255]  -  ['a'..'z','A'..'Z','1'..'9','0']


Standard word delimiters, used in the SearchBuf (1159   ) call.
28.2.3         Types

TCompareTextProc  =  function(const  AText:  String;const  AOther:  String)
                                                :  Boolean


Function prototype for comparing two string in AnsiResemblesText (1142   )


TSoundexIntLength  =  1..8


Range of allowed integer soundex lengths.


TSoundexLength  =  1..MaxInt


Range of allowed soundex lengths.


TStringSeachOption  =  TStringSearchOption


There  is  an  typo  error  in  the  original  Borland  StrUtils  unit.  This  type  just  refers  to  the
correct TStringSearchOption (1137   ) and is provided for compatibility only.


TStringSearchOption  =  (soDown,soMatchCase,soWholeWord)
                    Table 28.2:  Enumeration values for type TStringSearchOption


                                __Value__________________Explanation__________________________
                                  soDown                 Search in down direction.
                                  soMatchCase            Match case
                                  soWholeWord            Search whole words only.
Possible options for SearchBuf (1159   ) call.


TStringSearchOptions=  Set  of  (soDown,soMatchCase,soWholeWord)


Set of options for SearchBuf (1159   ) call.



                                                                1137

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3          Procedures  and  functions



                28.3.1         AddChar

    Synopsis:    Add characters to the left of a string till a certain length

Declaration:     function  AddChar(C:  Char;const  S:  String;N:  Integer)  :  String

    Visibility:   default

Description:     AddChar adds characters (C ) to the left of S till the length N is reached,  and returns the
                resulting string.  If the length of S is already equal to or larger than N , then no characters are
                added.  The resulting string can be thought of as a right-aligned version of S , with length N
                .

       Errors:   None

    See also:    AddCharR (1138   ), PadLeft (1154   ), PadRight (1155   ), PadCenter (1154   )
                28.3.2         AddCharR

    Synopsis:    Add chars at the end of a string till it reaches a certain length

Declaration:     function  AddCharR(C:  Char;const  S:  String;N:  Integer)  :  String

    Visibility:   default

Description:     AddCharR adds characters (C) to the right of S till the length N is reached, and returns the
                resulting string.  If the length of  S is already equal to or larger than N, then no characters
                are added.  The resulting string can be thought of as a left-aligned version of  S, with length
                N .

       Errors:   None

    See also:    AddChar (1138   )
                28.3.3         AnsiContainsStr

    Synopsis:    Checks whether a string contains a given substring

Declaration:     function  AnsiContainsStr(const  AText:  String;const  ASubText:  String)
                                                         :  Boolean

    Visibility:   default

Description:     AnsiContainsString checks whether AText contains ASubText, and returns True if this is
                the case, or returns False otherwise.  The search is performed case-sensitive.

       Errors:   None

    See also:    AnsiContainsText (1139   ), AnsiEndsStr (1139   ), AnsiIndexStr (1139   ), AnsiStartsStr (1143   )
                                                                                1138

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.4         AnsiContainsText

    Synopsis:    Check whether a string contains a certain substring, ignoring case.

Declaration:     function  AnsiContainsText(const  AText:  String;const  ASubText:  String)
                                                           :  Boolean

    Visibility:   default

Description:     AnsiContainsString checks whether AText contains ASubText, and returns True if this is
                the case, or returns False otherwise.  The search is performed case-insensitive.

       Errors:

    See also:    AnsiContainsStr (1138   ), AnsiEndsText (1139   ), AnsiIndexText (1140   ), AnsiStartsText (1143   )
                28.3.5         AnsiEndsStr

    Synopsis:    Check whether a string ends with a certain substring

Declaration:     function  AnsiEndsStr(const  ASubText:  String;const  AText:  String)
                                                   :  Boolean

    Visibility:   default

Description:     AnsiEndsStr  checks  AText  to  see  whether  it  ends  with  ASubText,  and  returns  True  if  it
                does, False if not.  The check is performed case-sensitive.  Basically, it checks whether the
                position of  ASubText equals the length of  AText minus the length of  ASubText plus one.

       Errors:   None.

    See also:    AnsiEndsText (1139   ), AnsiStartsStr (1143   ), AnsiIndexStr (1139   ), AnsiContainsStr (1138   )
                28.3.6         AnsiEndsText

    Synopsis:    Check whether a string ends with a certain substring, ignoring case.

Declaration:     function  AnsiEndsText(const  ASubText:  String;const  AText:  String)
                                                     :  Boolean

    Visibility:   default

Description:     AnsiEndsStr checks AText to see whether it ends with ASubText , and returns True if it
                does, False if not.  The check is performed case-insensitive.  Basically, it checks whether the
                position of  ASubText equals the length of  AText minus the length of  ASubText plus one.

       Errors:   None

    See also:    AnsiStartsText (1143   ), AnsiEndsStr (1139   ), AnsiIndexText (1140   ), AnsiContainsText (1139   )
                28.3.7         AnsiIndexStr

    Synopsis:    Searches, observing case, for a string in an array of strings.

Declaration:     function  AnsiIndexStr(const  AText:  String;
                                                   const  AValues:  Array  of  String)  :  Integer

    Visibility:   default
                                                                                1139

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
Description:     AnsiIndexStr  matches  AText  against  each  string  in  AValues  .  If  a  match  is  found,  the
                corresponding index (zero-based) in the AValues array is returned.  If no match is found, -1
                is returned.  The strings are matched observing case.

       Errors:   None.

    See also:    AnsiIndexText (1140   ), AnsiMatchStr (1140   ), AnsiMatchText (1141   )
                28.3.8         AnsiIndexText

    Synopsis:    Searches, case insensitive, for a string in an array of strings.

Declaration:     function  AnsiIndexText(const  AText:  String;
                                                     const  AValues:  Array  of  String)  :  Integer

    Visibility:   default

Description:     AnsiIndexStr  matches  AText  against  each  string  in  AValues  .  If  a  match  is  found,  the
                corresponding index (zero-based) in the AValues array is returned.  If no match is found, -1
                is returned.  The strings are matched ignoring case.

       Errors:   None

    See also:    AnsiIndexStr (1139   ), AnsiMatchStr (1140   ), AnsiMatchText (1141   )
                28.3.9         AnsiLeftStr

    Synopsis:    Copies a number of characters starting at the left of a string

Declaration:     function  AnsiLeftStr(const  AText:  AnsiString;const  ACount:  Integer)
                                                   :  AnsiString

    Visibility:   default

Description:     AnsiLeftStr returns the ACount leftmost characters from AText.  If  ACount is larger than
                the length of AText, only as much characters as available in AText will be copied.  If ACount
                is zero or negative, no characters will be copied.  The characters are counted as characters,
                not as Bytes.

                This function corresponds to the Visual Basic LeftStr function.

       Errors:   None.

    See also:    AnsiMidStr  (1141   ),  AnsiRightStr  (1143   ),  LeftStr  (1152   ),  RightStr  (1158   ),  MidStr  (1153   ),
                LeftBStr (1152   ), RightBStr (1157   ), MidBStr (1153   )
                28.3.10          AnsiMatchStr

    Synopsis:    Check whether a string occurs in an array of strings, observing case.

Declaration:     function  AnsiMatchStr(const  AText:  String;
                                                   const  AValues:  Array  of  String)  :  Boolean

    Visibility:   default

Description:     AnsiIndexStr matches AText against each string in AValues.  If a match is found, it returns
                True, otherwise False is returned.  The strings are matched observing case.

                This function simply calls AnsiIndexStr (1139   ) and checks whether it returns -1 or not.

       Errors:



                                                                                1140

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.11          AnsiMatchText

    Synopsis:    Check whether a string occurs in an array of strings, disregarding case.

Declaration:     function  AnsiMatchText(const  AText:  String;
                                                     const  AValues:  Array  of  String)  :  Boolean

    Visibility:   default

Description:     AnsiIndexStr matches AText against each string in AValues.  If a match is found, it returns
                True, otherwise False is returned.  The strings are matched ignoring case.

                This function simply calls AnsiIndexText (1140   ) and checks whether it returns -1 or not.

       Errors:
                28.3.12          AnsiMidStr

    Synopsis:    Returns a number of characters copied from a given location in a string

Declaration:     function  AnsiMidStr(const  AText:  AnsiString;const  AStart:  Integer;
                                                const  ACount:  Integer)  :  AnsiString

    Visibility:   default

Description:     AnsiMidStr returns ACount characters from AText, starting at position AStart.  If AStart+ACount
                is larger than the length of  AText, only as much characters as available in AText (starting
                from AStart) will be copied.  If ACount is zero or negative, no characters will be copied.  The
                characters are counted as characters, not as Bytes.

                This function corresponds to the Visual Basic MidStr function.

       Errors:   None

    See also:    AnsiLeftStr  (1140   ),  AnsiRightStr  (1143   ),  LeftStr  (1152   ),  RightStr  (1158   ),  MidStr  (1153   ),
                LeftBStr (1152   ), RightBStr (1157   ), MidBStr (1153   )
                28.3.13          AnsiProperCase

    Synopsis:    Pretty-Print a string:  make lowercase and capitalize first letters of words

Declaration:     function  AnsiProperCase(const  S:  String;const  WordDelims:  TSysCharSet)
                                                        :  String

    Visibility:   default

Description:     AnsiProperCase  converts  S  to  an  all  lowercase  string,  but  capitalizes  the  first  letter  of
                every  word  in  the  string,  and  returns  the  resulting  string.  When  searching  for  words,  the
                characters in WordDelimiters are used to determine the boundaries of words.  The constant
                StdWordDelims (1137   ) can be used for this.

       Errors:
                                                                                1141

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.14          AnsiReplaceStr

    Synopsis:    Search and replace all occurrences of a string, case sensitive.

Declaration:     function  AnsiReplaceStr(const  AText:  String;const  AFromText:  String;
                                                      const  AToText:  String)  :  String

    Visibility:   default

Description:     AnsiReplaceString searches AText for all occurrences of the string AFromText and replaces
                them with AToText, and returns the resulting string.  The search is performed observing case.

       Errors:   None.

    See also:    AnsiReplaceText (1142   ), SearchBuf (1159   )
                28.3.15          AnsiReplaceText

    Synopsis:    Search and replace all occurrences of a string, case insensitive.

Declaration:     function  AnsiReplaceText(const  AText:  String;const  AFromText:  String;
                                                        const  AToText:  String)  :  String

    Visibility:   default

Description:     AnsiReplaceString searches AText for all occurrences of the string AFromText and replaces
                them with AToText , and returns the resulting string.  The search is performed ignoring case.

       Errors:   None.

    See also:    AnsiReplaceStr (1142   ), SearchBuf (1159   )
                28.3.16          AnsiResemblesText

    Synopsis:    Check whether 2 strings resemble each other.

Declaration:     function  AnsiResemblesText(const  AText:  String;const  AOther:  String)
                                                             :  Boolean

    Visibility:   default

Description:     AnsiResemblesText will check whether AnsiResemblesProc (1136   ) is set.  If it is not set,
                False  is  returned.   If  it  is  set,  AText  and  AOtherText  are  passed  to  it  and  it's  result  is
                returned.

       Errors:   None.

    See also:    AnsiResemblesProc (1136   ), SoundexProc (1160   )
                28.3.17          AnsiReverseString

    Synopsis:    Reverse the letters in a string.

Declaration:     function  AnsiReverseString(const  AText:  AnsiString)  :  AnsiString

    Visibility:   default

Description:     AnsiReverseString returns a string with all characters of  AText in reverse order.

                if the result of this function equals AText, AText is called an anagram.

       Errors:   None.



                                                                                1142

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.18          AnsiRightStr

    Synopsis:    Copies a number of characters starting at the right of a string

Declaration:     function  AnsiRightStr(const  AText:  AnsiString;const  ACount:  Integer)
                                                     :  AnsiString

    Visibility:   default

Description:     AnsiLeftStr returns the ACount rightmost characters from AText.  If ACount is larger than
                the length of AText, only as much characters as available in AText will be copied.  If ACount
                is zero or negative, no characters will be copied.  The characters are counted as characters,
                not as Bytes.

                This function corresponds to the Visual Basic RightStr function.

       Errors:   None.

    See also:    AnsiLeftStr  (1140   ),  AnsiMidStr  (1141   ),  LeftStr  (1152   ),  RightStr  (1158   ),  MidStr  (1153   ),
                LeftBStr (1152   ), RightBStr (1157   ), MidBStr (1153   )
                28.3.19          AnsiStartsStr

    Synopsis:    Check whether a string starts with a given substring, observing case

Declaration:     function  AnsiStartsStr(const  ASubText:  String;const  AText:  String)
                                                      :  Boolean

    Visibility:   default

Description:     AnsiStartsStr checks AText to see whether it starts with ASubText , and returns True if
                it does, False if not.  The check is performed case-sensitive.  Basically, it checks whether the
                position of  ASubText equals 1.

       Errors:

    See also:    AnsiEndsStr (1139   ), AnsiStartsStr (1143   ), AnsiIndexStr (1139   ), AnsiContainsStr (1138   )
                28.3.20          AnsiStartsText

    Synopsis:    Check whether a string starts with a given substring, ignoring case

Declaration:     function  AnsiStartsText(const  ASubText:  String;const  AText:  String)
                                                        :  Boolean

    Visibility:   default

Description:     AnsiStartsText checks AText to see whether it starts with ASubText , and returns True if
                it does, False if not.  The check is performed case-insensitive.  Basically, it checks whether
                the position of  ASubText equals 1.

       Errors:   None.

    See also:    AnsiEndsText (1139   ), AnsiStartsStr (1143   ), AnsiIndexText (1140   ), AnsiContainsText (1139   )
                                                                                1143

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.21          BinToHex

    Synopsis:    Convert a binary buffer to a hexadecimal string

Declaration:     procedure  BinToHex(BinValue:  PChar;HexValue:  PChar;BinBufSize:  Integer)

    Visibility:   default

Description:     BinToHex converts the byte values in BinValue to a string consisting of 2-charachter hex-
                adecimal strings in HexValue.  BufSize specifies the length of  BinValue, which means that
                HexValue must have size 2*BufSize.

                For example a buffer containing the byte values 255 and 0 will be converted to FF00.

       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    HexToBin (1150   )
                28.3.22          Copy2Space

    Synopsis:    Returns all characters in a string till the first space character (not included).

Declaration:     function  Copy2Space(const  S:  String)  :  String

    Visibility:   default

Description:     Copy2Space determines the position of the first space in the string S and returns all charac-
                ters up to this position.  The space character itself is not included in the result string.  The
                string S is left untouched.  If there is no space in S, then the whole string S is returned.

                This function simply calls Copy2Symb (1145   ) with the space (ASCII code 32) as the symbol
                argument.

       Errors:   None.

    See also:    Copy2Symb (1145   ), Copy2SpaceDel (1144   )
                28.3.23          Copy2SpaceDel

    Synopsis:    Deletes and returns all characters in a string till the first space character (not included).

Declaration:     function  Copy2SpaceDel(var  S:  String)  :  String

    Visibility:   default

Description:     Copy2SpaceDel  determines  the  position  of  the  first  space  in  the  string  S  and  returns  all
                characters up to this position.  The space character itself is not included in the result string.
                All returned characters, including the space, are deleted from the string S, after which it is
                right-trimmed.  If there is no space in S, then the whole string S is returned, and S itself is
                emptied.

                This  function  simply  calls  Copy2SymbDel  (1145   )  with  the  space  (ASCII  code  32)  as  the
                symbol argument.

       Errors:   None.

    See also:    Copy2SymbDel (1145   ), Copy2Space (1144   )

                                                                                1144

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.24          Copy2Symb

    Synopsis:    Returns all characters in a string till a given character (not included).

Declaration:     function  Copy2Symb(const  S:  String;Symb:  Char)  :  String

    Visibility:   default

Description:     Copy2SymbDel determines the position of the first occurrence of  Symb in the string S and
                returns all characters up to this position.  The Symb character itself is not included in the
                result string.  The string S is left untouched.  If  Symb does not appear in S, then the whole
                of  S is returned.

       Errors:   None.

    See also:    Copy2Space (1144   ), Copy2SymbDel (1145   )
                28.3.25          Copy2SymbDel

    Synopsis:    Deletes and returns all characters in a string till a given character (not included).

Declaration:     function  Copy2SymbDel(var  S:  String;Symb:  Char)  :  String

    Visibility:   default

Description:     Copy2SymbDel determines the position of the first occurrence of  Symb in the string S and
                returns all characters up to this position.  The Symb character itself is not included in the
                result string.  All returned characters, not including the Symb character, are deleted from the
                string S, after which it is right-trimmed.  If  Symb does not appear in S, then the whole of  S
                is returned, and S itself is emptied.

       Errors:   None.

    See also:    Copy2SpaceDel (1144   ), Copy2Symb (1145   )
                28.3.26          Dec2Numb

    Synopsis:    Convert a decimal number to a string representation, using given a base.

Declaration:     function  Dec2Numb(N:  LongInt;Len:  Byte;Base:  Byte)  :  String

    Visibility:   default

Description:     Dec2Numb  converts  N  to  its  representation  using  base  Base  .   The  resulting  string  is  left-
                padded with zeroes till it has length Len .  Base must be in the range 2-36 to be meaningful,
                but no checking on this is performed.

       Errors:   If  Base   is  out  of  range,  the  resulting  string  will  contain  unreadable  (non-alphanumeric)
                characters.

    See also:    Hex2Dec (1150   ), IntToBin (1150   ), intToRoman (1151   ), RomanToInt (1158   )
                                                                                1145

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.27          DecodeSoundexInt

    Synopsis:    Decodes the integer representation of a soundex code and returns the original soundex code.

Declaration:     function  DecodeSoundexInt(AValue:  Integer)  :  String

    Visibility:   default

Description:     DecodeSoundexInt  converts  the  integer  value  AValue  to  a  soundex  string.   It  performs
                the reverse operation of the SoundexInt (1160   ) function.  The result is the soundex string
                corresponding to AValue.  .

       Errors:   None.

    See also:    SoundexInt (1160   ), DecodeSoundexWord (1146   ), Soundex (1159   )
                28.3.28          DecodeSoundexWord

    Synopsis:    Decodes the word-sized representation of a soundex code and returns the original soundex
                code.

Declaration:     function  DecodeSoundexWord(AValue:  Word)  :  String

    Visibility:   default

Description:     DecodeSoundexWord  converts  the  integer  value  AValue  to  a  soundex  string.   It  performs
                the reverse operation of the SoundexWord (1161   ) function.  The result is the soundex string
                corresponding to AValue .

       Errors:   None.

    See also:    SoundexInt (1160   ), DecodeSoundexInt (1146   ), Soundex (1159   )
                28.3.29          DelChars

    Synopsis:    Delete all occurrences of a given character from a string.

Declaration:     function  DelChars(const  S:  String;Chr:  Char)  :  String

    Visibility:   default

Description:     DelChars returns a copy of  S with all Chr characters removed from it.

       Errors:   None.

    See also:    DelSpace (1146   ), DelSpace1 (1147   )
                28.3.30          DelSpace

    Synopsis:    Delete all occurrences of a space from a string.

Declaration:     function  DelSpace(const  S:  String)  :  String

    Visibility:   default

Description:     DelSpace returns a copy of  S with all spaces (ASCII code 32) removed from it.

       Errors:   None.

    See also:    DelChars (1146   ), DelSpace1 (1147   )



                                                                                1146

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.31          DelSpace1

    Synopsis:    Reduces sequences of space characters to 1 space character.

Declaration:     function  DelSpace1(const  S:  String)  :  String

    Visibility:   default

Description:     DelSpace1 returns a copy of  S with all sequences of spaces reduced to 1 space.

       Errors:   None.

    See also:    DelChars (1146   ), DelSpace (1146   )
                28.3.32          DupeString

    Synopsis:    Creates and concatenates N copies of a string

Declaration:     function  DupeString(const  AText:  String;ACount:  Integer)  :  String

    Visibility:   default

Description:     DupeString returns a string consisting of  ACount concatenations of  AText.  Thus


                DupeString('1234567890',3);


                will produce a string


                '123456789012345678901234567890'


       Errors:   None.
                28.3.33          ExtractDelimited

    Synopsis:    Extract the N-th delimited part from a string.

Declaration:     function  ExtractDelimited(N:  Integer;const  S:  String;
                                                         const  Delims:  TSysCharSet)  :  String

    Visibility:   default

Description:     ExtractDelimited extracts the N-th part from the string S. The set of characters in Delims
                are used to mark part boundaries.  When a delimiter is encountered, a new part is started
                and the old part is ended.  Another way of stating this is that any (possibly empty) series
                of  characters  not  in  Delims,  situated  between  2  characters  in  Delims,  it  is  considered  as
                piece of a part.  This means that if 2 delimiter characters appear next to each other, there
                is an empty part between it.  If an N-th part cannot be found, an empty string is returned.
                However, unlike ExtractWord (1148   ), an empty string is a valid return value, i.e.  a part can
                be empty.

                The pre-defined constant StdWordDelims (1137   ) can be used for the Delims argument.  The
                pre-defined  constant  Brackets  (1136   )  would  be  better  suited  the  Delims  argument  e.g.  in
                case factors in a mathematical expression are searched.

       Errors:   None.

    See also:    ExtractSubStr (1148   ), ExtractWord (1148   ), ExtractWordPos (1148   )

                                                                                1147

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.34          ExtractSubstr

    Synopsis:    Extract a word from a string, starting at a given position in the string.

Declaration:     function  ExtractSubstr(const  S:  String;var  Pos:  Integer;
                                                     const  Delims:  TSysCharSet)  :  String

    Visibility:   default

Description:     ExtractSubStr returns all characters from S starting at position Pos till the first character
                in  Delims,  or  till  the  end  of  S  is  reached.  The  delimiter  character  is  not  included  in  the
                result.  Pos is then updated to point to the next first non-delimiter character in S. If  Pos is
                larger than the Length of  S, an empty string is returned.

                The pre-defined constant StdWordDelims (1137   ) can be used for the Delims argument.

       Errors:   None.

    See also:    ExtractDelimited (1147   ), ExtractWord (1148   ), ExtractWordPos (1148   )
                28.3.35          ExtractWord

    Synopsis:    Extract the N-th word out of a string.

Declaration:     function  ExtractWord(N:  Integer;const  S:  String;
                                                 const  WordDelims:  TSysCharSet)  :  String

    Visibility:   default

Description:     ExtractWord extracts the N-th word from the string S. The set of characters in WordDelims
                are used to mark word boundaries.  A word is defined as any non-empty sequence of characters
                which are not present in WordDelims:  if a character is not in WordDelims, it is considered
                as part of a word.  If an N-th word cannot be found, an empty string is returned.

                Unlike  ExtractDelimited  (1147   ),  an  empty  string  is  not  a  valid  return  value,  i.e.  is  not  a
                word.  If an empty string is returned, the index N was out of range.

                The pre-defined constant StdWordDelims (1137   ) can be used for the WordDelims argument.

       Errors:   None.

    See also:    ExtractWordPos  (1148   ),  ExtractSubStr  (1148   ),  ExtractDelimited  (1147   ),  IsWordPresent
                (1152   ), WordCount (1163   ), WordPosition (1163   )
                28.3.36          ExtractWordPos

    Synopsis:    Extract a word from a string, and return the position where it was located in the string.

Declaration:     function  ExtractWordPos(N:  Integer;const  S:  String;
                                                      const  WordDelims:  TSysCharSet;var  Pos:  Integer)
                                                        :  String

    Visibility:   default

Description:     ExtractWordPos extracts the N-th word from the string S and returns the position of this
                word in Pos.  The set of characters in WordDelims are used to mark word boundaries.  A word
                is defined as any non-empty sequence of characters which are not present in WordDelims :  if
                a character is not in WordDelims , it is considered as part of a word.  If an N -th word cannot
                be found, an empty string is returned and Pos is zero.

                                                                                1148

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                Unlike  ExtractDelimited  (1147   ),  an  empty  string  is  not  a  valid  return  value,  i.e.  is  not  a
                word.  If an empty string is returned, the index N was out of range.

                The pre-defined constant StdWordDelims (1137   ) can be used for the WordDelims argument.

       Errors:   None.

    See also:    ExtractWord  (1148   ),  ExtractSubStr  (1148   ),  IsWordPresent  (1152   ),  WordCount  (1163   ),
                WordPosition (1163   )
                28.3.37          FindPart

    Synopsis:    Search for a substring in a string, using wildcards.

Declaration:     function  FindPart(const  HelpWilds:  String;const  InputStr:  String)
                                              :  Integer

    Visibility:   default

Description:     FindPart searches the string InputStr and returns the first string that matches the wild-
                cards  specification  in  HelpWilds  .   If  no  match  is  found,  and  empty  string  is  returned.
                Currently, the only valid wildcards is the "?" character.

       Errors:   None.

    See also:    SearchBuf (1159   )
                28.3.38          GetCmdLineArg

    Synopsis:    Returns the command-line argument following the given switch.

Declaration:     function  GetCmdLineArg(const  Switch:  String;SwitchChars:  TSysCharSet)
                                                      :  String

    Visibility:   default

Description:     GetCmdLineArg returns the value for the Switch option on the command-line, if any is given.
                Command-line  arguments  are  considered  switches  if  they  start  with  one  of  the  characters
                in  the  SwitchChars  set.   The  value  is  the  command-line  argument  following  the  switch
                command-line argument.

                Gnu-style (long) Options of the form switch=value are not supported.

                The StdSwitchChars (1137   ) constant can be used as value for the SwitchChars parameter.

       Errors:   The GetCmdLineArg does not check whether the value of the option does not start with a
                switch character.  i.e.


                myprogram  -option1  -option2


                will result in - ption2  s the result of the GetCmdLineArg call for option1.

    See also:    StdSwitchChars (1137   )

                                                                                1149

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.39          Hex2Dec

    Synopsis:    Converts a hexadecimal string to a decimal value

Declaration:     function  Hex2Dec(const  S:  String)  :  LongInt

    Visibility:   default

Description:     Hex2Dec  converts  the  hexadecimal  value  in  the  string  S  to  its  decimal  value.  Unlike  the
                standard Valor StrToInt functions, there need not be a $ sign in front of the hexadecimal
                value to indicate that it is indeed a hexadecimal value.

       Errors:   If S does not contain a valid hexadecimal value, an EConvertError exception will be raised.

    See also:    Dec2Numb (1145   ), IntToBin (1150   ), intToRoman (1151   ), RomanToInt (1158   )
                28.3.40          HexToBin

    Synopsis:    Convert a hexadecimal string to a binary buffer

Declaration:     function  HexToBin(HexValue:  PChar;BinValue:  PChar;BinBufSize:  Integer)
                                              :  Integer

    Visibility:   default

Description:     HexToBin scans the hexadecimal string representation in HexValue and transforms every 2
                character hexadecimal number to a byte and stores it in BinValue.  The buffer size is the
                size  of  the  binary  buffer.  Scanning  will  stop  if  the  size  of  the  binary  buffer  is  reached  or
                when an invalid character is encountered.  The return value is the number of stored bytes.

       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    BinToHex (1144   )
                28.3.41          IfThen

    Synopsis:    Returns one of two strings, depending on a boolean expression

Declaration:     function  IfThen(AValue:  Boolean;const  ATrue:  String;AFalse:  String)
                                           :  String
                function  IfThen(AValue:  Boolean;const  ATrue:  String)  :  String

    Visibility:   default

Description:     IfThen returns ATrue if  AValue is True, and returns AFalse if  AValue is false.

       Errors:   None.

    See also:    AnsiMatchStr (1140   ), AnsiMatchText (1141   )
                28.3.42          IntToBin

    Synopsis:    Converts an integer to a binary string representation, inserting spaces at fixed locations.

Declaration:     function  IntToBin(Value:  LongInt;Digits:  Integer;Spaces:  Integer)
                                              :  String
                function  IntToBin(Value:  LongInt;Digits:  Integer)  :  String
                function  intToBin(Value:  Int64;Digits:  Integer)  :  String
                                                                                1150

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
    Visibility:  default

Description:     IntToBin converts Value to a string with it's binary (base 2) representation.  The resulting
                string  contains  at  least  Digits  digits,  with  spaces  inserted  every  Spaces  digits.   Spaces
                should be a nonzero value.  If  Digits is larger than 32, it is truncated to 32.

       Errors:   If spaces is zero, a division by zero error will occur.

    See also:    Hex2Dec (1150   ), IntToRoman (1151   )
                28.3.43          IntToRoman

    Synopsis:    Represent an integer with roman numerals

Declaration:     function  IntToRoman(Value:  LongInt)  :  String

    Visibility:   default

Description:     IntToRoman converts Value to a string with the Roman representation of  Value.  Number
                up to 1 million can be represented this way.

       Errors:   None.

    See also:    RomanToInt (1158   ), Hex2Dec (1150   ), IntToBin (1150   )
                28.3.44          IsEmptyStr

    Synopsis:    Check whether a string is empty, disregaring whitespace characters

Declaration:     function  IsEmptyStr(const  S:  String;const  EmptyChars:  TSysCharSet)
                                                 :  Boolean

    Visibility:   default

Description:     IsEmptyStr returns True if the string S only contains characters whitespace characters, all
                characters in EmptyChars are considered whitespace characters.  If a character not present
                in EmptyChars is found in S, False is returned.

       Errors:   None.

    See also:    IsWild (1151   ), FindPart (1149   ), IsWordPresent (1152   )
                28.3.45          IsWild

    Synopsis:    Check whether a string matches a wildcard search expression.

Declaration:     function  IsWild(InputStr:  String;Wilds:  String;IgnoreCase:  Boolean)
                                           :  Boolean

    Visibility:   default

Description:     IsWild  checks  InputStr  for  the  presence  of  the  Wilds  string.   Wilds  may  contain  "?"
                and  "*"  wildcard  characters,  which  have  their  usual  meaning:  "*"  matches  any  series  of
                characters, possibly empty.  "?" matches any single character.  The function returns True if
                a string is found that matches Wilds, False otherwise.

                If  IgnoreCase is True, the non-wildcard characters are matched case insensitively.  If it is
                False, case is observed when searching.

       Errors:   None.

    See also:    SearchBuf (1159   ), FindPart (1149   )



                                                                                1151

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.46          IsWordPresent

    Synopsis:    Check for the presence of a word in a string.

Declaration:     function  IsWordPresent(const  W:  String;const  S:  String;
                                                     const  WordDelims:  TSysCharSet)  :  Boolean

    Visibility:   default

Description:     IsWordPresent checks for the presence of the word W in the string S. Words are delimited by
                the characters found in WordDelims.  The function returns True if a match is found, False
                otherwise.  The search is performed case sensitive.

                This function is equivalent to the SearchBuf (1159   ) function with the soWholeWords option
                specified.

       Errors:   None.

    See also:    SearchBuf (1159   )
                28.3.47          LeftBStr

    Synopsis:    Copies Count characters starting at the left of a string.

Declaration:     function  LeftBStr(const  AText:  AnsiString;const  AByteCount:  Integer)
                                              :  AnsiString

    Visibility:   default

Description:     LeftBStr returns a string containing the leftmost AByteCount bytes from the string AText .
                If AByteCount is larger than the length (in bytes) of AText , only as many bytes as available
                are returned.

       Errors:   None.

    See also:    LeftStr (1152   ), AnsiLeftStr (1140   ), RightBStr (1157   ), MidBStr (1153   )
                28.3.48          LeftStr

    Synopsis:    Copies Count characters starting at the left of a string.

Declaration:     function  LeftStr(const  AText:  AnsiString;const  ACount:  Integer)
                                            :  AnsiString
                function  LeftStr(const  AText:  WideString;const  ACount:  Integer)
                                            :  WideString

    Visibility:   default

Description:     LeftStr returns a string containing the leftmost ACount characters from the string AText
                .  If  ACount is larger than the length (in characters) of  AText , only as many characters as
                available are returned.

       Errors:   None.

    See also:    LeftBStr (1152   ), AnsiLeftStr (1140   ), RightStr (1158   ), MidStr (1153   )


                                                                                1152

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.49          MidBStr

    Synopsis:    Copies a number of characters starting at a given position in a string.

Declaration:     function  MidBStr(const  AText:  AnsiString;const  AByteStart:  Integer;
                                           const  AByteCount:  Integer)  :  AnsiString

    Visibility:   default

Description:     MidBStr returns a string containing the first AByteCount bytes from the string AText start-
                ing at position AByteStart.  If AByteStart+AByteCount is larger than the length (in bytes)
                of AText, only as many bytes as available are returned.  If AByteStart is less than 1 or larger
                than the length of  AText, then no characters are returned.

       Errors:   None.

    See also:    LeftBStr (1152   ), AnsiMidStr (1141   ), RightBStr (1157   ), MidStr (1153   )
                28.3.50          MidStr

    Synopsis:    Copies a number of characters starting at a given position in a string.

Declaration:     function  MidStr(const  AText:  AnsiString;const  AStart:  Integer;
                                         const  ACount:  Integer)  :  AnsiString
                function  MidStr(const  AText:  WideString;const  AStart:  Integer;
                                         const  ACount:  Integer)  :  WideString

    Visibility:   default

Description:     MidStr returns a string containing the first ACount bytes from the string AText starting at
                position AStart.  If  AStart+ACount is larger than the length (in characters) of  AText, only
                as  many  characters  as  available  are  returned.  If  AStart  is  less  than  1  or  larger  than  the
                length of  AText, then no characters are returned.

                This function is equivalent to the standard Copy function, and is provided for completeness
                only.

       Errors:   None.

    See also:    LeftStr (1152   ), AnsiMidStr (1141   ), RightStr (1158   ), MidBStr (1153   )
                28.3.51          NPos

    Synopsis:    Returns the position of the N-th occurence of a substring in a string.

Declaration:     function  NPos(const  C:  String;S:  String;N:  Integer)  :  Integer

    Visibility:   default

Description:     NPos checks S for the position of the N-th occurrence of  C. If  C occurs less than N times in
                S, or does not occur in S at all, 0 is returned.  If  N is less than 1, zero is returned.

       Errors:   None.

    See also:    WordPosition (1163   ), FindPart (1149   )


                                                                                1153

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.52          Numb2Dec

    Synopsis:    Converts a string representation of a number to its numerical value, given a certain base.

Declaration:     function  Numb2Dec(S:  String;Base:  Byte)  :  LongInt

    Visibility:   default

Description:     Numb2Dec  converts  the  number  in  string  S  to  a  decimal  value.  It  assumes  the  number  is
                represented using Base as the base.  No checking is performed to see whether S contains a
                valid number using base Base.

       Errors:   None.

    See also:    Hex2Dec (1150   ), Numb2USA (1154   )
                28.3.53          Numb2USA

    Synopsis:    Insert thousand separators.

Declaration:     function  Numb2USA(const  S:  String)  :  String

    Visibility:   default

Description:     Numb2USA inserts thousand separators in the string S at the places where they are supposed
                to be, i.e.  every 3 digits.  The string S should contain a valid integer number, i.e.  no digital
                number.  No checking on this is done.

       Errors:   None.
                28.3.54          PadCenter

    Synopsis:    Pad the string to a certain length, so the string is centered.

Declaration:     function  PadCenter(const  S:  String;Len:  Integer)  :  String

    Visibility:   default

Description:     PadCenter add spaces to the left and right of the string S till the result reaches length Len.
                If the number of spaces to add is odd, then the extra space will be added at the end.  If the
                string  S  has  length  equal  to  or  largert  than  Len,  no  spaces  are  added,  and  the  string  S  is
                returned as-is.

       Errors:   None.

    See also:    PadLeft (1154   ), PadRight (1155   ), AddChar (1138   ), AddCharR (1138   )
                28.3.55          PadLeft

    Synopsis:    Add spaces to the left of a string till a certain length is reached.

Declaration:     function  PadLeft(const  S:  String;N:  Integer)  :  String

    Visibility:   default

Description:     PadLeft add spaces to the left of the string S till the result reaches length Len .  If the string
                S has length equal to or largert than Len , no spaces are added, and the string S is returned
                as-is.  The resulting string is S , right-justified on length Len .

       Errors:   None.

    See also:    PadLeft (1154   ), PadCenter (1154   ), AddChar (1138   ), AddCharR (1138   )



                                                                                1154

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.56          PadRight

    Synopsis:    Add spaces to the right of a string till a certain length is reached.

Declaration:     function  PadRight(const  S:  String;N:  Integer)  :  String

    Visibility:   default

Description:     PadRight  add  spaces  to  the  left  of  the  string  S  till  the  result  reaches  length  Len.  If  the
                string  S  has  length  equal  to  or  largert  than  Len,  no  spaces  are  added,  and  the  string  S  is
                returned as-is.  The resulting string is S, left-justified on length Len .

       Errors:   None.

    See also:    PadLeft (1154   ), PadCenter (1154   ), AddChar (1138   ), AddCharR (1138   )
                28.3.57          PosEx

    Synopsis:    Search for the occurance of a character in a string, starting at a certain position.

Declaration:     function  PosEx(const  SubStr:  String;const  S:  String;Offset:  Cardinal)
                                         :  Integer
                function  PosEx(const  SubStr:  String;const  S:  String)  :  Integer
                function  PosEx(c:  Char;const  S:  String;Offset:  Cardinal)  :  Integer

    Visibility:   default

Description:     PosEx returns the position of the first occurrence of the character C or the substring SubStr
                in the string S, starting the search at position Offset (default 1).  If  C or SubStr does not
                occur in S after the given Offset, zero is returned.  The position Offset is also searched.

       Errors:   None.

    See also:    NPos (1153   ), AnsiContainsText (1139   ), AnsiContainsStr (1138   )
                28.3.58          PosSet

    Synopsis:    Return the position in a string of any character out of a set of characters

Declaration:     function  PosSet(const  c:  TSysCharSet;const  s:  ansistring)  :  Integer
                function  PosSet(const  c:  String;const  s:  ansistring)  :  Integer

    Visibility:   default

Description:     PosSet returns the position in s of the first found character which is in the set c.  If none
                of the characters in c is found in s, then 0 is returned.

       Errors:   None.

    See also:    PosEx (1155   ), PosSetEx (1155   ), #rtl.system.pos (1301   ), RPosEx (1158   )
                28.3.59          PosSetEx

    Synopsis:    Return  the  position  in  a  string  of  any  character  out  of  a  set  of  characters,  starting  at  a
                certain position
                                                                                1155

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
Declaration:     function  PosSetEx(const  c:  TSysCharSet;const  s:  ansistring;
                                            count:  Integer)  :  Integer
                function  PosSetEx(const  c:  String;const  s:  ansistring;count:  Integer)
                                             :  Integer

    Visibility:  default

Description:     PosSetEx returns the position in s of the first found character which is in the set c,  and
                starts  searching  at  character  position  Count.  If  none  of  the  characters  in  c  is  found  in  s,
                then 0 is returned.

       Errors:   None.

    See also:    PosEx (1155   ), PosSet (1155   ), #rtl.system.pos (1301   ), RPosEx (1158   )
                28.3.60          RandomFrom

    Synopsis:    Choose a random string from an array of strings.

Declaration:     function  RandomFrom(const  AValues:  Array  of  String)  :  String;    Overload

    Visibility:   default

Description:     RandomFrom picks at random a valid index in the array AValues and returns the string at
                that position in the array.

       Errors:   None.

    See also:    AnsiMatchStr (1140   ), AnsiMatchText (1141   )
                28.3.61          Removeleadingchars

    Synopsis:    Remove any leading characters in a set from a string

Declaration:     procedure  Removeleadingchars(var  S:  AnsiString;const  CSet:  TSysCharset)

    Visibility:   default

Description:     Removeleadingchars removes any starting characters from S that appear in the set CSet.
                It  stops  removing  characters  as  soon  as  a  character  not  in  CSet  is  encountered.   This  is
                similar in behaviour to TrimLeft (1490   ) which used whitespace as the set.

       Errors:   None.

    See also:    rtl.sysutils.TrimLeft (1136   ), RemoveTrailingChars (1157   ), RemovePadChars (1156   ), Trim-
                LeftSet (1162   )
                28.3.62          RemovePadChars

    Synopsis:    Remove any trailing or leading characters in a set from a string

Declaration:     procedure  RemovePadChars(var  S:  AnsiString;const  CSet:  TSysCharset)

    Visibility:   default

Description:     RemovePadChars removes any leading trailing characters from S that appear in the set CSet,
                i.e.  it starts with the last character and works its way to the start of the string, and it stops
                removing  characters  as  soon  as  a  character  not  in  CSet  is  encountered.   Then  the  same
                procedure is repeated starting from the beginning of the string.  This is similar in behaviour
                to Trim (1490   ) which used whitespace as the set.



                                                                                1156

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
       Errors:   None.

    See also:    rtl.sysutils.Trim (1136   ), RemoveLeadingChars (1156   ), RemoveTrailingChars (1157   ), Trim-
                Set (1163   ), TrimLeftSet (1162   ), TrimRightSet (1162   )
                28.3.63          RemoveTrailingChars

    Synopsis:    Remove any trailing characters in a set from a string

Declaration:     procedure  RemoveTrailingChars(var  S:  AnsiString;const  CSet:  TSysCharset)

    Visibility:   default

Description:     RemoveTrailingChars removes any trailing characters from S that appear in the set CSet,
                i.e.  it starts with the last character and works its way to the start of the string.  It stops
                removing  characters  as  soon  as  a  character  not  in  CSet  is  encountered.  This  is  similar  in
                behaviour to TrimRight (1491   ) which used whitespace as the set.

       Errors:

    See also:    rtl.sysutils.TrimLeft (1136   ), RemoveLeadingChars (1156   ), TrimRightSet (1162   )
                28.3.64          ReverseString

    Synopsis:    Reverse characters in a string

Declaration:     function  ReverseString(const  AText:  String)  :  String

    Visibility:   default

Description:     ReverseString returns a string, made up of the characters in string AText, in reverse order.

       Errors:   None.

    See also:    RandomFrom (1156   )
                28.3.65          RightBStr

    Synopsis:    Copy a given number of characters (bytes), counting from the right of a string.

Declaration:     function  RightBStr(const  AText:  AnsiString;const  AByteCount:  Integer)
                                                :  AnsiString

    Visibility:   default

Description:     RightBStr  returns  a  string  containing  the  rightmost  AByteCount  bytes  from  the  string
                AText.  If  AByteCount is larger than the length (in bytes) of  AText, only as many bytes as
                available are returned.

       Errors:   None.

    See also:    LeftBStr (1152   ), AnsiRightStr (1143   ), RightStr (1158   ), MidBStr (1153   )

                                                                                1157

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.66          RightStr

    Synopsis:    Copy a given number of characters, counting from the right of a string.

Declaration:     function  RightStr(const  AText:  AnsiString;const  ACount:  Integer)
                                              :  AnsiString
                function  RightStr(const  AText:  WideString;const  ACount:  Integer)
                                              :  WideString

    Visibility:   default

Description:     RightStr returns a string containing the rightmost ACount characters from the string AText
                .  If  ACount is larger than the length (in characters) of  AText , only as many characters as
                available are returned.

       Errors:   None.

    See also:    LeftStr (1152   ), AnsiRightStr (1143   ), RightBStr (1157   ), MidStr (1153   )
                28.3.67          RomanToInt

    Synopsis:    Convert a string with a Roman number to it's decimal value.

Declaration:     function  RomanToInt(const  S:  String)  :  LongInt

    Visibility:   default

Description:     RomanToInt returns the decimal equivalent of the Roman numerals in the string S. Invalid
                characters are dropped from S. A negative numeral is supported as well.

       Errors:   None.

    See also:    IntToRoman (1151   ), Hex2Dec (1150   ), Numb2Dec (1154   )
                28.3.68          RPos

    Synopsis:    Find last occurrence of substring or character in a string

Declaration:     function  RPos(c:  Char;const  S:  AnsiString)  :  Integer;    Overload
                function  RPos(const  Substr:  AnsiString;const  Source:  AnsiString)
                                       :  Integer;    Overload

    Visibility:   default

Description:     RPos looks in S for the character C or the string SubStr.  It starts looking at the end of the
                string, and searches towards the beginning of the string.  If a match is found, it returns the
                position of the match.

    See also:    RPosEx (1158   )
                28.3.69          RPosex

    Synopsis:    Find last occurrence substring or character in a string, starting at a certain position

Declaration:     function  RPosEX(C:  Char;const  S:  AnsiString;offs:  cardinal)  :  Integer
                                         ;    Overload
                function  RPosex(const  Substr:  AnsiString;const  Source:  AnsiString;
                                         offs:  cardinal)  :  Integer;    Overload



                                                                                1158

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
    Visibility:  default

Description:     RPos looks in S for the character C or the string SubStr.  It starts looking at position Offs,
                and searches towards the beginning of the string.  If a match is found, it returns the position
                of the match.

    See also:    RPos (1158   )
                28.3.70          SearchBuf

    Synopsis:    Search a buffer for a certain string.

Declaration:     function  SearchBuf(Buf:  PChar;BufLen:  Integer;SelStart:  Integer;
                                              SelLength:  Integer;SearchString:  String;
                                              Options:  TStringSearchOptions)  :  PChar
                function  SearchBuf(Buf:  PChar;BufLen:  Integer;SelStart:  Integer;
                                              SelLength:  Integer;SearchString:  String)  :  PChar

    Visibility:   default

Description:     SearchBuf searches the buffer Buf for the occurrence of  SearchString.  At must Buflen
                characters  are  searched,  and  the  search  is  started  at  SelStart+SelLength.  If  a  match  is
                found,  a  pointer  to  the  position  of  the  match  is  returned.  The  parameter  Options  (1137   )
                specifies how the search is conducted.  It is a set of the following options:



                                                                       Table 28.3:



                __Option_________________Effect____________________________________________________________________________________*
 *___________________
                  soDown                 Searches forward, starting at the end of the selection.  Default is searching up
                  soMatchCase            Observe case when searching.  Default is to ignore case.
                  soWholeWord            Match only whole words.  Default also returns parts of words
                The standard constant WordDelimiters (1137   ) is used to mark the boundaries of words.

                The SelStart parameter is zero based.

       Errors:   Buflen must be the real length of the string, no checking on this is performed.

    See also:    FindPart (1149   ), ExtractWord (1148   ), ExtractWordPos (1148   ), ExtractSubStr (1148   ), Is-
                WordPresent (1152   )
                28.3.71          Soundex

    Synopsis:    Compute the soundex of a string

Declaration:     function  Soundex(const  AText:  String;ALength:  TSoundexLength)  :  String
                function  Soundex(const  AText:  String)  :  String

    Visibility:   default

Description:     Soundex computes a soundex code for AText.  The resulting code will at most have ALength
                characters.  The soundex code is computed according to the US system of soundex computing,
                which may result in inaccurate results in other languages.

       Errors:   None.



                                                                                1159

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
    See also:    SoundexCompare  (1160   ),  SoundexInt  (1160   ),  SoundexProc  (1160   ),  SoundexWord  (1161   ),
                SoundexSimilar (1161   )
                28.3.72          SoundexCompare

    Synopsis:    Compare soundex values of 2 strings.

Declaration:     function  SoundexCompare(const  AText:  String;const  AOther:  String;
                                                      ALength:  TSoundexLength)  :  Integer
                function  SoundexCompare(const  AText:  String;const  AOther:  String)
                                                        :  Integer

    Visibility:   default

Description:     SoundexCompare  computes  the  soundex  codes  of  AText  and  AOther  and  feeds  these  to
                CompareText.  It will return -1 if the soundex code of  AText is less than the soundex code
                of AOther, 0 if they are equal, and 1 if the code of AOther is larger than the code of AText.

       Errors:   None.

    See also:    Soundex (1159   ), SoundexInt (1160   ), SoundexProc (1160   ), SoundexWord (1161   ), SoundexSim-
                ilar (1161   )
                28.3.73          SoundexInt

    Synopsis:    Soundex value as an integer.

Declaration:     function  SoundexInt(const  AText:  String;ALength:  TSoundexIntLength)
                                                 :  Integer
                function  SoundexInt(const  AText:  String)  :  Integer

    Visibility:   default

Description:     SoundexInt computes the Soundex (1159   ) code (with length ALength, default 4) of AText,
                and converts the code to an integer value.

       Errors:   None.

    See also:    Soundex (1159   ), SoundexCompare (1160   ), SoundexProc (1160   ), SoundexWord (1161   ), SoundexSim-
                ilar (1161   )
                28.3.74          SoundexProc

    Synopsis:    Default AnsiResemblesText implementation.

Declaration:     function  SoundexProc(const  AText:  String;const  AOther:  String)  :  Boolean

    Visibility:   default

Description:     SoundexProc is the standard implementation for the AnsiResemblesText (1142   ) procedure:
                By default,  AnsiResemblesProc is set to this function.  It compares the soundex codes of
                AOther and AText and returns True if they are equal, or False if they are not.

       Errors:   None.

    See also:    Soundex (1159   ), SoundexCompare (1160   ), SoundexInt (1160   ), SoundexWord (1161   ), SoundexSim-
                ilar (1161   )
                                                                                1160

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.75          SoundexSimilar

    Synopsis:    Check whether 2 strings have equal soundex values

Declaration:     function  SoundexSimilar(const  AText:  String;const  AOther:  String;
                                                      ALength:  TSoundexLength)  :  Boolean
                function  SoundexSimilar(const  AText:  String;const  AOther:  String)
                                                        :  Boolean

    Visibility:   default

Description:     SoundexSimilar  returns  True  if  the  soundex  codes  (with  length  ALength)  of  AText  and
                AOther are equal, and False if they are not.

       Errors:   None.

    See also:    Soundex (1159   ), SoundexCompare (1160   ), SoundexInt (1160   ), SoundexProc (1160   ), Soundex-
                Word (1161   ), Soundex (1159   )
                28.3.76          SoundexWord

    Synopsis:    Calculate a word-sized soundex value

Declaration:     function  SoundexWord(const  AText:  String)  :  Word

    Visibility:   default

Description:     SoundexInt computes the Soundex (1159   ) code (with length 4) of AText , and converts the
                code to a word-sized value.

       Errors:   None.

    See also:    Soundex (1159   ), SoundexCompare (1160   ), SoundexInt (1160   ), SoundexProc (1160   ), SoundexSim-
                ilar (1161   )
                28.3.77          StringsReplace

    Synopsis:    Replace occurrences of a set of strings to another set of strings

Declaration:     function  StringsReplace(const  S:  String;OldPattern:  Array  of  String;
                                                      NewPattern:  Array  of  String;Flags:  TReplaceFlags)
                                                        :  String

    Visibility:   default

Description:     StringsReplace scans S for the occurrence of one of the strings in OldPattern and replaces
                it with the corresponding string in NewPattern.  It takes into account Flags, which has the
                same meaning as in StringReplace (1469   ).

                Corresponding strings are matched by location:  the N-th string in OldPattern is replaced
                by the N-th string in NewPattern.  Note that this means that the number of strings in both
                arrays must be the same.

       Errors:   If the number of strings in both arrays is different, then an exception is raised.

    See also:    #rtl.sysutils.StringReplace (1469   ), #rtl.sysutils.TReplaceFlags (1372   )

                                                                                1161

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.78          StuffString

    Synopsis:    Replace part of a string with another string.

Declaration:     function  StuffString(const  AText:  String;AStart:  Cardinal;
                                                 ALength:  Cardinal;const  ASubText:  String)  :  String

    Visibility:   default

Description:     StuffString  returns  a  copy  of  AText  with  the  segment  starting  at  AStart  with  length
                ALength, replaced with the string ASubText.  Basically it deletes the segment of  Atext and
                inserts the new text in it's place.

       Errors:   No  checking  on  the  validity  of  the  AStart  and  ALength  parameters  is  done.   Providing
                invalid values may result in access violation errors.

    See also:    FindPart  (1149   ),  DelChars  (1146   ),  DelSpace  (1146   ),  ExtractSubStr  (1148   ),  DupeString
                (1147   )
                28.3.79          Tab2Space

    Synopsis:    Convert tab characters to a number of spaces

Declaration:     function  Tab2Space(const  S:  String;Numb:  Byte)  :  String

    Visibility:   default

Description:     Tab2Space  returns  a  copy  of  S  with  all  tab  characters  (ASCII  character  9)  converted  to
                Numb spaces.

       Errors:   None.

    See also:    StuffString (1162   ), FindPart (1149   ), ExtractWord (1148   ), DelChars (1146   ), DelSpace (1146   ),
                DelSpace1 (1147   ), DupeString (1147   )
                28.3.80          TrimLeftSet

    Synopsis:    Remove any leading characters in a set from a string and returns the result

Declaration:     function  TrimLeftSet(const  S:  String;const  CSet:  TSysCharSet)  :  String

    Visibility:   default

Description:     TrimLeftSet  performs  the  same  action  as  RemoveLeadingChars  (1156   ),  but  returns  the
                resulting string.

       Errors:   None.

    See also:    rtl.sysutils.TrimLeft (1136   ), RemoveLeadingChars (1156   ), RemoveTrailingChars (1157   ), Re-
                movePadChars (1156   ), TrimSet (1163   ), TrimRightSet (1162   )
                28.3.81          TrimRightSet

    Synopsis:    Remove any trailing characters in a set from a string and returns the result

Declaration:     function  TrimRightSet(const  S:  String;const  CSet:  TSysCharSet)  :  String

    Visibility:   default
                                                                                1162

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
Description:     TrimLeftSet  performs  the  same  action  as  RemoveTrailingChars  (1157   ),  but  returns  the
                resulting string.

       Errors:   None.

    See also:    rtl.sysutils.TrimRight  (1136   ),  RemoveLeadingChars  (1156   ),  RemoveTrailingChars  (1157   ),
                RemovePadChars (1156   ), TrimSet (1163   ), TrimLeftSet (1162   )
                28.3.82          TrimSet

    Synopsis:    Remove any leading or trailing characters in a set from a string and returns the result

Declaration:     function  TrimSet(const  S:  String;const  CSet:  TSysCharSet)  :  String

    Visibility:   default

Description:     TrimSet  performs  the  same  action  as  RemovePadChars  (1156   ),  but  returns  the  resulting
                string.

       Errors:   None.

    See also:    rtl.sysutils.Trim  (1136   ),  RemoveLeadingChars  (1156   ),  RemoveTrailingChars  (1157   ),  Re-
                movePadChars (1156   ), TrimRightSet (1162   ), TrimLeftSet (1162   )
                28.3.83          WordCount

    Synopsis:    Count the number of words in a string.

Declaration:     function  WordCount(const  S:  String;const  WordDelims:  TSysCharSet)
                                                :  Integer

    Visibility:   default

Description:     WordCount returns the number of words in the string  S. A word is a non-empty string of
                characters bounded by one of the characters in WordDelims.

                The pre-defined StdWordDelims (1137   ) constant can be used for the WordDelims argument.

       Errors:   None.

    See also:    WordPosition (1163   ), StdWordDelims (1137   ), ExtractWord (1148   ), ExtractWordPos (1148   )
                28.3.84          WordPosition

    Synopsis:    Search position of Nth word in a string.

Declaration:     function  WordPosition(const  N:  Integer;const  S:  String;
                                                   const  WordDelims:  TSysCharSet)  :  Integer

    Visibility:   default

Description:     WordPosition returns the position (in characters) of the N-th word in the string S. A word
                is a non-empty string of characters bounded by one of the characters in WordDelims.  If N is
                out of range, zero is returned.

                The pre-defined StdWordDelims (1137   ) constant can be used for the WordDelims argument.

       Errors:   None

    See also:    WordCount (1163   ), StdWordDelims (1137   ), ExtractWord (1148   ), ExtractWordPos (1148   )



                                                                                1163

                _______________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________
                28.3.85          XorDecode

    Synopsis:    Decode a string encoded with XorEncode (1164   )

Declaration:     function  XorDecode(const  Key:  String;const  Source:  String)  :  String

    Visibility:   default

Description:     XorDecode decodes Source and returns the original string that was encrypted using XorEn-
                code (1164   ) with key Key.  If a different key is used than the key used to encode the string,
                the result will be unreadable.

       Errors:   If the string Source is not a valid XorEncode result (e.g.  contains non-numerical characters),
                then a EConversionError exception will be raised.

    See also:    XorEncode (1164   ), XorString (1164   )
                28.3.86          XorEncode

    Synopsis:    Encode a string by XOR-ing its characters using characters of a given key, representing the
                result as hex values.

Declaration:     function  XorEncode(const  Key:  String;const  Source:  String)  :  String

    Visibility:   default

Description:     XorEncode encodes the string Source by XOR-ing each character in Source with the corre-
                sponding character in Key (repeating Key as often as necessary) and representing the resulting
                ASCII code as a hexadecimal number (of length 2).  The result is therefore twice as long as
                the original string, and every 2 bytes represent an ASCII code.

                Feeding the resulting string with the same key  Key to the XorDecode (1164   ) function will
                result in the original Source string.

                This function can be used e.g.  to trivially encode a password in a configuration file.

       Errors:   None.

    See also:    XorDecode (1164   ), XorString (1164   ), Hex2Dec (1150   )
                28.3.87          XorString

    Synopsis:    Encode a string by XOR-ing its characters using characters of a given key.

Declaration:     function  XorString(const  Key:  ShortString;const  Src:  ShortString)
                                                :  ShortString

    Visibility:   default

Description:     XorString  encodes  the  string  Src  by  XOR-ing  each  character  in  Source  with  the  corre-
                sponding  character  in  Key,  repeating  Key  as  often  as  necessary.  The  resulting  string  may
                contain unreadable characters and may even contain null characters.  For this reason it may
                be a better idea to use the XorEncode (1164   ) function instead, which will representing each
                resulting ASCII code as a hexadecimal number (of length 2).

                Feeding the result again to XorString with the same Key, will result in the original string
                Src.

       Errors:   None.

    See also:    XorEncode (1164   ), XorDecode (1164   )
                                                                                1164


Chapter   29


Reference   for   unit   'System'
29.1          Miscellaneous  functions


Functions that do not belong in one of the other categories.



                                                       Table 29.1:

                    __Name______________________Description________________________________________________
                      Assert (1216   )          Conditionally abort program with error
                      Break (1221   )           Abort current loop
                      Continue (1229   )        Next cycle in current loop
                      Exclude (1239   )         Exclude an element from a set
                      Exit (1241   )            Exit current function or procedure
                      Include (1257   )         Include an element into a set
                      LongJmp (1270   )         Jump to execution point
                      Ord (1299   )             Return ordinal value of enumerated type
                      Pred (1302   )            Return previous value of ordinal type
                      SetJmp (1316   )          Mark execution point for jump
                      SizeOf (1322   )          Return size of variable or type
                      Succ (1327   )            Return next value of ordinal type



29.2          Operating  System  functions


Functions that are connected to the operating system.
29.3          String  handling


All things connected to string handling.
29.4          Mathematical  routines


Functions connected to calculating and coverting numbers.
                                                            1165

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___

                                                       Table 29.2:

         __Name__________________________Description__________________________________________________________________
           Chdir (1222   )               Change working directory
           Getdir (1250   )              Return current working directory
           Halt (1253   )                Halt program execution
           Paramcount (1299   )          Number of parameters with which program was called
           Paramstr (1300   )            Retrieve parameters with which program was called
           Mkdir (1271   )               Make a directory
           Rmdir (1310   )               Remove a directory
           Runerror (1313   )            Abort program execution with error condition

                                                       Table 29.3:

           __Name____________________________Description____________________________________________________________
             BinStr (1219   )                Construct binary representation of integer
             Chr (1223   )                   Convert ASCII code to character
             Concat (1229   )                Concatenate two strings
             Copy (1230   )                  Copy part of a string
             Delete (1233   )                Delete part of a string
             HexStr (1254   )                Construct hexadecimal representation of integer
             Insert (1262   )                Insert one string in another
             Length (1267   )                Return length of string
             Lowercase (1270   )             Convert string to all-lowercase
             OctStr (1274   )                Construct octal representation of integer
             Pos (1301   )                   Calculate position of one string in another
             SetLength (1317   )             Set length of a string
             SetString (1318   )             Set contents and length of a string
             Str (1325   )                   Convert number to string representation
             StringOfChar (1325   )          Create string consisting of a number of characters
             Upcase (1335   )                Convert string to all-uppercase
             Val (1337   )                   Convert string to number

29.5          Memory  management  functions


Functions concerning memory issues.
29.6          File  handling  functions


Functions concerning input and output from and to file.
29.7          Overview


The system unit contains the standard supported functions of Free Pascal.  It is the same for
all platforms.  Basically it is the same as the system unit provided with Borland or Turbo
Pascal.

Functions  are  listed  in  alphabetical  order.  Arguments  of  functions  or  procedures  that  are
                                                                1166

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___

                                                       Table 29.4:

          __Name_________________________Description________________________________________________________________
            Abs (1211   )                Calculate absolute value
            Arctan (1215   )             Calculate inverse tangent
            Cos (1231   )                Calculate cosine of angle
            Dec (1232   )                Decrease value of variable
            Exp (1242   )                Exponentiate
            Frac (1248   )               Return fractional part of floating point value
            Hi (1254   )                 Return high byte/word of value
            Inc (1256   )                Increase value of variable
            Int (1262   )                Calculate integer part of floating point value
            Ln (1268   )                 Calculate logarithm
            Lo (1268   )                 Return low byte/word of value
            Odd (1274   )                Is a value odd or even ?
            Pi (1300   )                 Return the value of pi
            Power (1165   )              Raise float to integer power
            Random (1303   )             Generate random number
            Randomize (1304   )          Initialize random number generator
            Round (1311   )              Round floating point value to nearest integer number
            Sin (1321   )                Calculate sine of angle
            Sqr (1323   )                Calculate the square of a value
            Sqrt (1324   )               Calculate the square root of a value
            Swap (1328   )               Swap high and low bytes/words of a variable
            Trunc (1333   )              Truncate a floating point value

optional are put between square brackets.

The  pre-defined  constants  and  variables  are  listed  in  the  first  section.  The  second  section
contains an overview of all functions, grouped by functionality, and the last section contains
the supported functions and procedures.
29.8          Constants,  types  and  variables



29.8.1         Constants

AbstractErrorProc  :  TAbstractErrorProc  =  nil


If set, the AbstractErrorProc constant is used when an abstract error occurs.  If it is not
set, then the standard error handling is done:  A stack dump is performed, and the program
exits with error code 211.

The SysUtils unit sets this procedure and raises an exception in its handler.


AllFilesMask  =  '*'


AllFilesMask is the wildcard that can be used to return all files in a directory.  On windows
and dos based systems, this will be '*.*', while for unix systems, this will be '*'.


AllowDirectorySeparators  :  Set  of  Char  =  ['\','/']


                                                                1167

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___

                                                       Table 29.5:

    __Name________________________________________Description______________________________________________________________
      Addr (1213   )                              Return address of variable
      Assigned (1217   )                          Check if a pointer is valid
      CompareByte (1224   )                       Compare 2 memory buffers byte per byte
      CompareChar (1225   )                       Compare 2 memory buffers byte per byte
      CompareDWord (1227   )                      Compare 2 memory buffers byte per byte
      CompareWord (1228   )                       Compare 2 memory buffers byte per byte
      CSeg (1231   )                              Return code segment
      Dispose (1234   )                           Free dynamically allocated memory
      DSeg (1235   )                              Return data segment
      FillByte (1244   )                          Fill memory region with 8-bit pattern
      Fillchar (1245   )                          Fill memory region with certain character
      FillDWord (1245   )                         Fill memory region with 32-bit pattern
      Fillword (1246   )                          Fill memory region with 16-bit pattern
      Freemem (1248   )                           Release allocated memory
      Getmem (1251   )                            Allocate new memory
      GetMemoryManager (1251   )                  Return current memory manager
      High (1255   )                              Return highest index of open array or enumerated
      IsMemoryManagerSet (1266   )                Is the memory manager set
      Low (1270   )                               Return lowest index of open array or enumerated
      Move (1272   )                              Move data from one location in memory to another
      MoveChar0 (1272   )                         Move data till first zero character
      New (1273   )                               Dynamically allocate memory for variable
      Ofs (1275   )                               Return offset of variable
      Ptr (1302   )                               Combine segment and offset to pointer
      ReAllocMem (1307   )                        Resize a memory block on the heap
      Seg (1316   )                               Return segment
      SetMemoryManager (1318   )                  Set a memory manager
      Sptr (1323   )                              Return current stack pointer
      SSeg (1324   )                              Return stack segment register value

AllowDirectorySeparators is the set of characters which are considered directory separa-
tors  by  the  RTL  units.   By  default,  this  is  set  to  the  most  common  directory  separators:
forward  slash  and  backslash,  so  routines  will  work  in  a  cross-platform  manner,  no  matter
which character was used:


AllowDirectorySeparators  :  set  of  char  =  ['\','/'];


If a more strict behaviour is desired, then AllowDirectorySeparators can be set to the only
character  allowed  on  the  current  operating  system,  and  all  RTL  routines  that  handle  file-
names (splitting filenames, extracting parts of the filename and so on) will use that character
only.


AllowDriveSeparators  :  Set  of  Char  =  []


AllowDriveSeparators are the characters which are considered to separate the drive part
from the directory part in a filename.  This will be an empty set on systems that do not sup-
port drive letters.  Other systems (dos, windows and OS/2) will have the colon (:)  character
as the only member of this set.
                                                                1168

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___

                                                       Table 29.6:

               __Name_________________________Description_______________________________________________________
                 Append (1214   )             Open a file in append mode
                 Assign (1216   )             Assign a name to a file
                 Blockread (1220   )          Read data from a file into memory
                 Blockwrite (1221   )         Write data from memory to a file
                 Close (1223   )              Close a file
                 Eof (1237   )                Check for end of file
                 Eoln (1238   )               Check for end of line
                 Erase (1239   )              Delete file from disk
                 Filepos (1242   )            Position in file
                 Filesize (1243   )           Size of file
                 Flush (1247   )              Write file buffers to disk
                 IOresult (1265   )           Return result of last file IO operation
                 Read (1304   )               Read from file into variable
                 Readln (1306   )             Read from file into variable and goto next line
                 Rename (1308   )             Rename file on disk
                 Reset (1308   )              Open file for reading
                 Rewrite (1310   )            Open file for writing
                 Seek (1314   )               Set file position
                 SeekEof (1314   )            Set file position to end of file
                 SeekEoln (1315   )           Set file position to end of line
                 SetTextBuf (1318   )         Set size of file buffer
                 Truncate (1334   )           Truncate the file at position
                 Write (1340   )              Write variable to file
                 WriteLn (1341   )            Write variable to file and append newline

AssertErrorProc  :  TAssertErrorProc  =  @SysAssert


If set, the AbstractErrorProc constant is used when an assert error occurs.  If it is not set,
then the standard error handling is done:  The assertion error message is printed, together
with the location of the assertion, and A stack dump is performed, and the program exits
with error code 227.

The SysUtils unit sets this procedure and raises an exception in its handler.


BackTraceStrFunc  :  TBackTraceStrFunc  =  @SysBackTraceStr


This handler is called to get a standard format for the backtrace routine.


CtrlZMarksEOF  :  Boolean  =  false


CtrlZMarksEOF indicates whether on this system, an CTRL-Z character (ordinal 26) in a file
marks the end of the file.  This is False on most systems except on DOS.

To get DOS-compatible behaviour, this constant can be set to True


DefaultStackSize  =  32768


Default size for a new thread's stack (32k by default).


DefaultTextLineBreakStyle  :  TTextLineBreakStyle  =  tlbsLF



                                                                1169

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
DefaultTextLineBreakStyle contains the default OS setting for the TTextLineBreakStyle
(1203   ) type.  It is initizliaed by the system unit,  and is used to determine the default line
ending when writing to text files.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


DirectorySeparator  =  '/'


DirectorySeparator  is  the  character  used  by  the  current  operating  system  to  separate
directory parts in a pathname.  This constant is system dependent, and should not be set.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


DriveSeparator  =  '/'


On systems that support driveletters, the DriveSeparator constant denotes the character
that separates the drive indicator from the directory part in a filename path.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


Erroraddr  :  pointer  =  nil


Address where the last error occurred.


Errorcode  :  Word  =  0


Last error code.


ErrorProc  :  TErrorProc  =  nil


If set,  the ErrorProc constant is used when a run-time error occurs.  If it is not set,  then
the standard error handling is done:  a stack dump is performed, and the program exits with
the indicated error code.

The SysUtils unit sets this procedure and raises an exception in its handler.


ExceptProc  :  TExceptProc  =  nil


This  constant  points  to  the  current  exception  handling  procedure.   This  routine  is  called
when  an  unhandled  exception  occurs,  i.e.   an  exception  that  is  not  stopped  by  a  except
block.

If the handler is not set, the RTL will emit a run-time error 217 when an unhandler exception
occurs.

It is set by the sysutils (1356   ) unit.


ExitProc  :  pointer  =  nil


Exit procedure pointer.


ExtensionSeparator  =  '.'



                                                                1170

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
ExtensionSeparator is the character which separates the filename from the file extension.
On all current platforms, this is the .  (dot) character.  All RTL filename handling routines
use this constant.


E_NOINTERFACE  =  hresult  (  $80004002  )


Interface call result:  Error:  not an interface


E_NOTIMPL  =  hresult  (  $80004001  )


Interface call result:  Interface not implemented


E_UNEXPECTED  =  hresult  (  $8000FFFF  )


Interface call result:  Unexpected error


Filemode  :  Byte  =  2


Default file mode for untyped files.


FileNameCaseSensitive  :  Boolean  =  true


FileNameCaseSensitive is True if case is important when using filenames on the current
OS. In this case, the OS will treat files with different cased names as different files.  Note that
this may depend on the filesystem:  Unix operating systems that access a DOS or Windows
partition  will  have  this  constant  set  to  true,  but  when  writing  to  the  DOS  partition,  the
casing is ignored.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


float_flag_denormal  =  2


IEC/IEEE floating-point exception flag:  ?


float_flag_divbyzero  =  4


IEC/IEEE floating-point exception flag:  Division by zero error


float_flag_inexact  =  32


IEC/IEEE floating-point exception flag:  ?


float_flag_invalid  =  1


IEC/IEEE floating-point exception flag:  Invalid operation error


float_flag_overflow  =  8


IEC/IEEE floating-point exception flag:  Overflow error


float_flag_underflow  =  16



                                                                1171

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
IEC/IEEE floating-point exception flag:  Underflow error


fmAppend  =  $D7B4


File mode:  File is open for writing, appending to the end.


fmClosed  =  $D7B0


File mode:  File is closed.


fmInOut  =  $D7B3


File mode:  File is open for reading and writing.


fmInput  =  $D7B1


File mode:  File is open for reading.


fmOutput  =  $D7B2


File mode:  File is open for writing.


fpc_in_abs_real  =  127


FPC compiler internal procedure index:  abs (real)


fpc_in_addr_x  =  42


FPC compiler internal procedure index:  addr


fpc_in_arctan_real  =  130


FPC compiler internal procedure index:  arctan (real)


fpc_in_assert_x_y  =  41


FPC compiler internal procedure index:  assert


fpc_in_assigned_x  =  19


FPC compiler internal procedure index:  assigned


fpc_in_bitsizeof_x  =  61


FPC compiler internal procedure index:  bitsizeof


fpc_in_break  =  39


FPC compiler internal procedure index:  break


fpc_in_chr_byte  =  7



                                                                1172

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
FPC compiler internal procedure index:  chr


fpc_in_concat_x  =  18


FPC compiler internal procedure index:  concat


fpc_in_const_abs  =  101


FPC compiler internal procedure index:  abs


fpc_in_const_odd  =  102


FPC compiler internal procedure index:  sqr


fpc_in_const_ptr  =  103


FPC compiler internal procedure index:  sqr


fpc_in_const_sqr  =  100


FPC compiler internal procedure index:  sqr


fpc_in_const_swap_long  =  105


FPC compiler internal procedure index:  swap (long)


fpc_in_const_swap_qword  =  108


FPC compiler internal procedure index:  swap (qword)


fpc_in_const_swap_word  =  104


FPC compiler internal procedure index:  swap (word)


fpc_in_continue  =  40


FPC compiler internal procedure index:  continue


fpc_in_copy_x  =  49


FPC compiler internal procedure index:  copy


fpc_in_cos_real  =  125


FPC compiler internal procedure index:  cos (real)


fpc_in_cycle  =  52


FPC compiler internal procedure index:  cycle


fpc_in_dec_x  =  36



                                                                1173

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
FPC compiler internal procedure index:  dec


fpc_in_dispose_x  =  47


FPC compiler internal procedure index:  dispose


fpc_in_exclude_x_y  =  38


FPC compiler internal procedure index:  exclude


fpc_in_exit  =  48


FPC compiler internal procedure index:  exit


fpc_in_exp_real  =  124


FPC internal compiler routine:  in_exp_real


fpc_in_fillchar_x  =  55


FPC internal compiler routine:  in_fillchar_x


fpc_in_finalize_x  =  45


FPC compiler internal procedure index:  finalize


fpc_in_frac_real  =  122


FPC internal compiler routine:  in_frac_real


fpc_in_get_caller_addr  =  57


FPC internal compiler routine:  in_get_caller_addr


fpc_in_get_caller_frame  =  58


FPC internal compiler routine:  in_get_caller_frame


fpc_in_get_frame  =  56


FPC internal compiler routine:  in_get_frame


fpc_in_high_x  =  28


FPC compiler internal procedure index:  high


fpc_in_hi_long  =  4


FPC compiler internal procedure index:  hi (long)


fpc_in_hi_qword  =  107



                                                                1174

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
FPC compiler internal procedure index:  hi (qword)


fpc_in_hi_word  =  2


FPC compiler internal procedure index:  hi (word)


fpc_in_include_x_y  =  37


FPC compiler internal procedure index:  include


fpc_in_inc_x  =  35


FPC compiler internal procedure index:  inc


fpc_in_initialize_x  =  50


FPC compiler internal procedure index:  initialize


fpc_in_int_real  =  123


FPC internal compiler routine:  in_int_real


fpc_in_leave  =  51


FPC compiler internal procedure index:  leave


fpc_in_length_string  =  6


FPC compiler internal procedure index:  length


fpc_in_ln_real  =  131


FPC compiler internal procedure index:  ln (real)


fpc_in_low_x  =  27


FPC compiler internal procedure index:  low


fpc_in_lo_long  =  3


FPC compiler internal procedure index:  lo (long)


fpc_in_lo_qword  =  106


FPC compiler internal procedure index:  lo (qword)


fpc_in_lo_word  =  1


FPC compiler internal procedure index:  lo (word)


fpc_in_mmx_pcmpeqb  =  200



                                                                1175

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
FPC compiler internal procedure index:  MMX


fpc_in_mmx_pcmpeqd  =  202


FPC compiler internal procedure index:  MMX


fpc_in_mmx_pcmpeqw  =  201


FPC compiler internal procedure index:  MMX


fpc_in_mmx_pcmpgtb  =  203


FPC compiler internal procedure index:  MMX


fpc_in_mmx_pcmpgtd  =  205


FPC compiler internal procedure index:  MMX


fpc_in_mmx_pcmpgtw  =  204


FPC compiler internal procedure index:  MMX


fpc_in_move_x  =  54


FPC internal compiler routine:  in_move_x


fpc_in_new_x  =  46


FPC compiler internal procedure index:  new


fpc_in_ofs_x  =  21


FPC compiler internal procedure index:  ofs


fpc_in_ord_x  =  5


FPC compiler internal procedure index:  ord


fpc_in_pack_x_y_z  =  59


FPC compiler internal procedure index:  pack


fpc_in_pi_real  =  126


FPC internal compiler routine:  in_pi_real


fpc_in_pred_x  =  30


FPC compiler internal procedure index:  pred


fpc_in_prefetch_var  =  109



                                                                1176

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
FPC compiler internal procedure index:  prefetch


fpc_in_readln_x  =  17


FPC compiler internal procedure index:  readln


fpc_in_read_x  =  16


FPC compiler internal procedure index:  read


fpc_in_reset_typedfile  =  32


FPC compiler internal procedure index:  reset


fpc_in_reset_x  =  25


FPC compiler internal procedure index:  reset


fpc_in_rewrite_typedfile  =  33


FPC compiler internal procedure index:  rewrite


fpc_in_rewrite_x  =  26


FPC compiler internal procedure index:  rewrite


fpc_in_round_real  =  121


FPC internal compiler routine:  in_round_real


fpc_in_seg_x  =  29


FPC compiler internal procedure index:  seg


fpc_in_setlength_x  =  44


FPC compiler internal procedure index:  setlength


fpc_in_settextbuf_file_x  =  34


FPC compiler internal procedure index:  settextbuf


fpc_in_sin_real  =  132


FPC compiler internal procedure index:  sin (real)


fpc_in_sizeof_x  =  22


FPC compiler internal procedure index:  sizeof


fpc_in_slice  =  53



                                                                1177

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
FPC internal compiler routine:  in_slice


fpc_in_sqrt_real  =  129


FPC compiler internal procedure index:  sqrt (real)


fpc_in_sqr_real  =  128


FPC compiler internal procedure index:  sqr (real)


fpc_in_str_x_string  =  20


FPC compiler internal procedure index:  str


fpc_in_succ_x  =  31


FPC compiler internal procedure index:  succ


fpc_in_trunc_real  =  120


FPC internal compiler routine:  in_trunc_real


fpc_in_typeinfo_x  =  43


FPC compiler internal procedure index:  typeinfo


fpc_in_typeof_x  =  23


FPC compiler internal procedure index:  typeof


fpc_in_unpack_x_y_z  =  60


FPC compiler internal procedure index:  unpack


fpc_in_val_x  =  24


FPC compiler internal procedure index:  val


fpc_in_writeln_x  =  15


FPC compiler internal procedure index:  writeln


fpc_in_write_x  =  14


FPC compiler internal procedure index:  write


growheapsize1  :  PtrInt  =  256  *  1024


Grow rate for block less than 256 Kb.


growheapsize2  :  PtrInt  =  1024  *  1024



                                                                1178

               __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'_________________*
 *__________________
               Grow rate for block larger than 256 Kb.


               growheapsizesmall  :  PtrInt  =  32  *  1024


               Fixed size small blocks grow rate


               InitProc  :  Pointer  =  nil


               InitProc is a routine that can be called after all units were initialized.  It can be set by units
               to execute code that can be initialized after all units were initialized.

Remark:         When setting the value of InitProc, the previous value should always be saved, and called
               when the installed initialization routine has finished executing.


               IsMultiThread  :  longbool  =  false


               Indicates whether more than one thread is running in the application.


               LFNSupport  =  true


               LFNSupport determines whether the current OS supports long file names, i.e.  filenames that
               are not of the form 8.3 as on ancient DOS systems.  If the value of this constant is True then
               long filenames are supported.  If it is false, then not.

               This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
               constants should be used instead of hardcoding OS characteristics.


               LineEnding  =  #10


               LineEnding is a constant which contains the current line-ending character.  This character
               is system dependent, and is initialized by the system.  It should not be set.

               This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
               constants should be used instead of hardcoding OS characteristics.


               maxExitCode  =  255


               maxExitCode is the maximum value for the Halt (1253   ) call.


               maxint  =  maxsmallint


               Maximum integer value.


               MaxKeptOSChunks  :  DWord  =  4


               MaxKeptOSChunks tells the heap manager how many free chunks of OS-allocated memory it
               should keep in memory.  When freeing memory, it can happen that a memory block obtained
               from the OS is completely free.  If more than MaxKeptOSChunks such blocks are free, then
               the heap manager will return them to the OS, to reduce memory requirements.


               maxLongint  =  $7fffffff


               Maximum longint value.



                                                                               1179

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
MaxPathLen  =  4096


This constant is system dependent.


MaxSIntValue  =  High  (  ValSInt  )


Maximum String-size value.


maxSmallint  =  32767


Maximum smallint value.


MaxUIntValue  =  High  (  ValUInt  )


Maximum unsigned integer value.


Max_Frame_Dump  :  Word  =  8


Maximum number of frames to show in error frame dump.


ModuleIsCpp  :  Boolean  =  false


ModuleIsCpp is always false for FPC programs, it is provided for Delphi compatibility only.


ModuleIsLib  :  Boolean  =  false


ModuleIsLib is set by the compiler when linking a library, program or package, and deter-
mines whether the current module is a library (or package) (True) or program (False).


ModuleIsPackage  :  Boolean  =  false


ModuleIsLib is set by the compiler when linking a library, program or package, and deter-
mines whether the current module is a package (True) or a library or program (False).


PathSeparator  =  ':'


PathSeparator is the character used commonly on the current operating system to separate
paths in a list of paths, such as the PATH environment variable.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


RaiseMaxFrameCount  :  LongInt  =  16


Maximum number of frames to include in TExceptObject (1198   )


RaiseProc  :  TExceptProc  =  nil


Procedure to raise an exception.


RT_ACCELERATOR  =  MAKEINTRESOURCE  (  9  )



                                                                1180

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Constant identifying an accelerator resouce


RT_BITMAP  =  MAKEINTRESOURCE  (  2  )


Constant identifying a bitmap resource


RT_CURSOR  =  MAKEINTRESOURCE  (  1  )


Constant identifying a cursor resource


RT_DIALOG  =  MAKEINTRESOURCE  (  5  )


Constant identifying a dialog resource


RT_FONT  =  MAKEINTRESOURCE  (  8  )


Constant identifying a font resource


RT_FONTDIR  =  MAKEINTRESOURCE  (  7  )


Constant identifying a font directory resource


RT_GROUP_CURSOR  =  MAKEINTRESOURCE  (  12  )


Constant identifying a group cursor resource


RT_GROUP_ICON  =  MAKEINTRESOURCE  (  13  )


Constant identifying a group icon resource


RT_ICON  =  MAKEINTRESOURCE  (  3  )


Constant identifying an icon resource


RT_MENU  =  MAKEINTRESOURCE  (  4  )


Constant identifying a menu resource


RT_MESSAGETABLE  =  MAKEINTRESOURCE  (  11  )


Constant identifying a message data resource


RT_RCDATA  =  MAKEINTRESOURCE  (  10  )


Constant identifying a binary data resource


RT_STRING  =  MAKEINTRESOURCE  (  6  )


Constant identifying a string table resource


RT_VERSION  =  MAKEINTRESOURCE  (  16  )



                                                                1181

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Constant identifying a version info resource


RuntimeErrorExitCodes  :  Array[TRuntimeError]  of  Byte  =  (0,203,204,200,201,215,207,200,205,206,219,216,218,217,202,220,221,222*
 *,223,224,225,227,212,228,229,233,234  )


This array is used by the Error (1239   ) routine to to convert a TRuntimeError (1202   ) enu-
meration type to a process exit code.


SafeCallErrorProc  :  TSafeCallErrorProc  =  nil


SafeCallErrorProc is a Handler called in case of a safecall calling convention error.  Error
is  the  error  number  (passed  by  the  Windows  operating  system)  and  Addr  is  the  address
where the error occurred.


SIGSTKSZ  =  40960
sLineBreak  =  LineEnding


sLineBreak is an alias for LineEnding (1179   ) and is supplied for Delphi compatibility.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


StackError  :  Boolean  =  false


Indicate whether there was a stack error.


StdErrorHandle  =  2


Value of the OS handle for the standard error-output file.


StdInputHandle  =  0


Value of the OS handle for the standard input file.


StdOutputHandle  =  1


Value of the OS handle for the standard output file.


S_FALSE  =  1


Interface call result:  Not OK


S_OK  =  0


Interface call result:  OK


ThreadingAlreadyUsed  :  Boolean  =  false


Internal constant for the threading system.  Don't use.


UnusedHandle  =  -1



                                                                1182

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Value indicating an unused file handle (as reported by the OS).


VarAddRefProc  :  procedure(var  v:  tvardata)  =  nil


Callback to increase reference count of a variant.


varany  =  $101


Variant type:  Any


vararray  =  $2000


Variant type:  variant Array


varboolean  =  11


Variant type:  Boolean type


varbyref  =  $4000


Variant type:  By reference


varbyte  =  17


Variant type:  Byte (8 bit)


VarClearProc  :  procedure(var  v:  tvardata)  =  nil


Callback to clear a variant.


VarCopyProc  :  procedure(var  d:  tvardata;const  s:  tvardata)  =  nil


Callback to copy a variant


varcurrency  =  6


Variant type:  Currency


vardate  =  7


Variant type:  Date


vardecimal  =  14


Variant type:  Decimal (BCD)


vardispatch  =  9


Variant type:  dispatch interface


vardouble  =  5



                                                                1183

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Variant type:  Double float


varempty  =  0


Variant type:  Empty variant


varerror  =  10


Variant type:  Error type


varint64  =  20


Variant type:  Integer (64-Bit)


varinteger  =  3


Variant type:  Integer (32-bit)


varlongword  =  19


Variant type:  Word (32 bit)


varnull  =  1


Variant type:  Null (1274   ) variant


varolestr  =  8


Variant type:  OLE string (widestring)


varqword  =  21


Variant type:  Word (64-bit)


varrecord  =  36
varshortint  =  16


Variant type:  Shortint (16 bit)


varsingle  =  4


Variant type:  Single float


varsmallint  =  2


Variant type:  smallint (8 bit)


varstrarg  =  $48



                                                                1184

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Variant type:  String


varstring  =  $100


Variant type:  String


VarToLStrProc  :  procedure(var  d:  AnsiString;const  s:  tvardata)  =  nil


Callback to convert a variant to a ansistring.


VarToWStrProc  :  procedure(var  d:  WideString;const  s:  tvardata)  =  nil


Callback to convert a variant to a widestring.


vartypemask  =  $fff


Variant type:  Mask to extract type


varunknown  =  13


Variant type:  Unknown


varvariant  =  12


Variant type:  Variant (arrays only)


varword  =  18


Variant type:  Word (16 bit)


varword64  =  varqword


Variant type:  Word (64-bit)


vmtAfterConstruction  =  vmtMethodStart  +  sizeof  (  pointer  )  *  5


VMT Layout:  ?


vmtAutoTable  =  vmtParent  +  sizeof  (  pointer  )  *  7


VMT layout:  ?


vmtBeforeDestruction  =  vmtMethodStart  +  sizeof  (  pointer  )  *  6


VMT Layout:  ?


vmtClassName  =  vmtParent  +  sizeof  (  pointer  )


VMT Layout:  location of class name.


vmtDefaultHandler  =  vmtMethodStart  +  sizeof  (  pointer  )  *  4



                                                                1185

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
VMT Layout:  ?


vmtDefaultHandlerStr  =  vmtMethodStart  +  sizeof  (  pointer  )  *  7


VMT Layout:  ?


vmtDestroy  =  vmtMethodStart


VMT Layout:  Location of destructor pointer.


vmtDynamicTable  =  vmtParent  +  sizeof  (  pointer  )  *  2


VMT Layout:  location of dynamic methods table.


vmtFieldTable  =  vmtParent  +  sizeof  (  pointer  )  *  4


VMT Layout:  Location of fields table.


vmtFreeInstance  =  vmtMethodStart  +  sizeof  (  pointer  )  *  2


VMT Layout:  location of FreeInstance method.


vmtInitTable  =  vmtParent  +  sizeof  (  pointer  )  *  6


VMT Layout:  ?


vmtInstanceSize  =  0


VMT Layout:  Location of class instance size in VMT


vmtIntfTable  =  vmtParent  +  sizeof  (  pointer  )  *  8


VMT layout:  Interface table


vmtMethodStart  =  vmtParent  +  sizeof  (  pointer  )  *  10


VMT layout:  start of method table.


vmtMethodTable  =  vmtParent  +  sizeof  (  pointer  )  *  3


VMT Layout:  Method table start.


vmtMsgStrPtr  =  vmtParent  +  sizeof  (  pointer  )  *  9


VMT layout:  message strings table.


vmtNewInstance  =  vmtMethodStart  +  sizeof  (  pointer  )


VMT Layout:  location of NewInstance method.


vmtParent  =  sizeof  (  ptrint  )  *  2



                                                                1186

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
VMT Layout:  location of pointer to parent VMT.


vmtSafeCallException  =  vmtMethodStart  +  sizeof  (  pointer  )  *  3


VMT Layout:  ?


vmtTypeInfo  =  vmtParent  +  sizeof  (  pointer  )  *  5


VMT Layout:  Location of class type information.


vtAnsiString  =  11


TVarRec type:  Ansistring


vtBoolean  =  1


TVarRec type:  Boolean


vtChar  =  2


TVarRec type:  Char


vtClass  =  8


TVarRec type:  Class type


vtCurrency  =  12


TVarRec type:  Currency


vtExtended  =  3


TVarRec type:  Extended


vtInt64  =  16


TVarRec type:  Int64 (signed 64-bit integer)


vtInteger  =  0


TVarRec type:  Integer


vtInterface  =  14


TVarRec type:  Interface


vtObject  =  7


TVarRec type:  Object instance


vtPChar  =  6



                                                                1187

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
TVarRec type:  PChar


vtPointer  =  5


TVarRec type:  pointer


vtPWideChar  =  10


TVarRec type:  PWideChar


vtQWord  =  17


TVarRec type:  QWord (unsigned 64-bit integer)


vtString  =  4


TVarRec type:  String


vtVariant  =  13


TVarRec type:  Variant


vtWideChar  =  9


TVarRec type:  Widechar


vtWideString  =  15


TVarRec type:  WideString
29.8.2         Types

AnsiChar  =  Char


Alias for 1-byte sized char.


Cardinal  =  LongWord


An unsigned 32-bits integer.


DWord  =  LongWord


An unsigned 32-bits integer


HGLOBAL  =  Cardinal


This is an opaque type.


HMODULE  =  Cardinal
                                                                1188

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
This is an opaque type.


HRESULT  =  LongInt


32-Bit signed integer.


IInterface  =  IUnknown


IInterface is the basic interface from which all COM style interfaces descend.


Integer  =  SmallInt


The  system  unit  defines  Integer  as  a  signed  16-bit  integer.  But  when  DELPHI  or  OBJFPC
mode are active, then the objpas unit redefines Integer as a 32-bit integer.


IntegerArray  =  Array[0..$effffff]  of  Integer


Generic array of integer.


jmp_buf  =  packed  record
   ebx  :  LongInt;
   esi  :  LongInt;
   edi  :  LongInt;
   bp  :  Pointer;
   sp  :  Pointer;
   pc  :  Pointer;
end
Record type to store processor information.


MAKEINTRESOURCE  =  PChar


Alias for the PChar (1190   ) type.


PAnsiChar  =  PChar


Alias for PChar (1190   ) type.


PAnsiString  =  ^AnsiString


Pointer to an ansistring type.


PBoolean  =  ^Boolean


Pointer to a Boolean type.


PByte  =  ^Byte


Pointer to byte (1165   ) type



                                                                1189

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
pcalldesc  =  ^tcalldesc


Pointer to TCallDesc (1197   ) record.


PCardinal  =  ^Cardinal


Pointer to Cardinal (1188   ) type


PChar  =  ^Char


Or the same as a pointer to an array of char.  See the reference manual for more information
about this type.


PClass  =  ^TClass


Pointer to TClass (1197   )


PCurrency  =  ^Currency


Pointer to currency type.


PDate  =  ^TDateTime


Pointer to a TDateTime (1197   ) type.


PDateTime  =  ^TDateTime


Pointer to TDatetime


PDispatch  =  ^IDispatch


Pointer to IDispatch (1342   ) interface type


pdispdesc  =  ^tdispdesc


Pointer to tdispdesc (1197   ) record


PDouble  =  ^Double


Pointer to double-sized float value.


PDWord  =  ^DWord


Pointer to DWord (1188   ) type


pdynarrayindex  =  ^tdynarrayindex


Pointer to tdynarrayindex (1197   ) type.


pdynarraytypeinfo  =  ^tdynarraytypeinfo



                                                                1190

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Pointer to TDynArrayTypeInfo (1198   ) type.


PError  =  ^TError


Pointer to an Error (1239   ) type.


PEventState  =  pointer


Pointer to EventState, which is an opaque type.


PExceptObject  =  ^TExceptObject


Pointer to Exception handler procedural type TExceptProc (1198   )


PExtended  =  ^Extended


Pointer to extended-sized float value.


PGuid  =  ^TGuid


Pointer to TGUID (1199   ) type.


PInt64  =  ^Int64


Pointer to Int64 type


PInteger  =  ^Integer


Pointer to integer (1189   ) type


PIntegerArray  =  ^IntegerArray


Pointer to IntegerArray (1189   ) type


pinterfaceentry  =  ^tinterfaceentry


Pointer to tinterfaceentry (1200   ) record.


pinterfacetable  =  ^tinterfacetable


Pointer to tinterfacetable (1200   ) record.


PJmp_buf  =  ^jmp_buf


Pointer to jmp_buf (1189   ) record


PLongBool  =  ^LongBool


Pointer to a LongBool type.


PLongint  =  ^LongInt



                                                                1191

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Pointer to Longint (1165   ) type


PLongWord  =  ^LongWord


Pointer to LongWord type


PMemoryManager  =  ^TMemoryManager


Pointer to TMemoryManager (1200   ) record


PMsgStrTable  =  ^TMsgStrTable


Pointer to array of TMsgStrTable (1201   ) records.


PointerArray  =  Array[0..512*1024*1024-2]  of  Pointer


Generic pointer array.


POleVariant  =  ^OleVariant


Pointer to OleVariant type.


PPAnsiChar  =  PPChar


Alias for PPChar (1192   ) type.


PPChar  =  ^PChar


Pointer to an array of pointers to null-terminated strings.


PPCharArray  =  ^TPCharArray


Pointer to TPCharArray (1201   ) type.


PPDispatch  =  ^PDispatch


Pointer to PDispatch (1190   ) pointer type


PPointer  =  ^Pointer


Pointer to a pointer type.


PPointerArray  =  ^PointerArray


Pointer to PointerArray (1192   ) type


PPPointer  =  ^PPointer


Pointer to a PPointer (1192   ) type.


PPtrInt  =  ^PtrInt



                                                                1192

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Pointer to PtrInt (1194   ) type.


PPtrUInt  =  ^PtrUInt


Pointer to unsigned integer of pointer size


PPUnknown  =  ^PUnknown


Pointer to untyped pointer


PPWideChar  =  ^PWideChar


Pointer to link id="PWideChar"> type.


PQWord  =  ^QWord


Pointer to QWord type


PRTLCriticalSection  =  ^TRTLCriticalSection


Pointer to #rtl.system.TRTLCriticalSection (1201   ) type.


PRTLEvent  =  pointer


Pointer to RTLEvent, which is an opaque type.


PShortInt  =  ^ShortInt


Pointer to shortint (1165   ) type


PShortString  =  ^ShortString


Pointer to a shortstring type.


PSingle  =  ^Single


Pointer to single-sized float value.


PSizeInt  =  ^SizeInt


Pointer to a SizeInt (1195   ) type


PSmallInt  =  ^SmallInt


Pointer to smallint (1165   ) type


pstringmessagetable  =  ^TStringMessageTable


Pointer to TStringMessageTable (1203   ) record.


PText  =  ^Text



                                                                1193

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Pointer to text file.


PtrInt  =  LongInt


Ptrint  is  a  signed  integer  type  which  has  always  the  same  size  as  a  pointer.   Ptrint  is
considered harmfull and should almost never be used in actual code,  because pointers are
normally unsigned.  For example, consider the following code:


getmem(p,2048);                            {Assume  the  address  of  p  becomes  $7ffffff0.}
q:=pointer(ptrint(p)+1024));       {Overflow  error.}
writeln(q>p);                                {Incorrect  answer.}


Ptrint  might  have  a  valid  use  when  two  pointers  are  substracted  from  each  other  if  it  is
unknown  which  pointer  has  the  largest  address.  However,  even  in  this  case  ptrint  causes
trouble in case the distance is larger than high(ptrint) and must be used with great care.

The introduction of the ptrint type was a mistake.  Please use ptruint (1194   ) instead.


PtrUInt  =  DWord


PtrUInt  is  an  unsigned  integer  type  which  has  always  the  same  size  as  a  pointer.  When
using integers which will be cast to pointers and vice versa, use this type, never the regular
Cardinal type.


PUCS2Char  =  PWideChar


Pointer to UCS2Char (1208   ) character.


PUCS4Char  =  ^UCS4Char


Pointer to UCS4Char (1208   )


PUCS4CharArray  =  ^TUCS4CharArray


Pointer to array of UCS4Char (1208   ) characters.


PUnknown  =  ^IUnknown


Untyped pointer


PUTF8String  =  ^UTF8String


Pointer to UTF8String (1209   )


pvararray  =  ^tvararray


Pointer to TVarArray (1205   ) type.


pvararraybound  =  ^tvararraybound


Pointer to tvararraybound (1205   ) type.



                                                                1194

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
pvararrayboundarray  =  ^tvararrayboundarray


Pointer to tvararrayboundarray (1206   ) type.


pvararraycoorarray  =  ^tvararraycoorarray


Pointer to tvararraycoorarray (1206   ) type.


pvardata  =  ^tvardata


Pointer to TVarData (1206   ) record.


PVariant  =  ^Variant


Pointer to Variant type.


pvariantmanager  =  ^tvariantmanager


Pointer to TVariantManager (1207   ) record.


PVarRec  =  ^TVarRec


Pointer to TVarRec (1208   ) type.


PWideChar  =  ^WideChar


Pointer to WChar (1209   ).


PWideString  =  ^WideString


Pointer to widestring type


PWord  =  ^Word


Pointer to word (1165   ) type


PWordBool  =  ^WordBool


Pointer to a WordBool type.


Real  =  Double


Alias for real type


real48  =  Array[0..5]  of  Byte


TP compatible real type (6 bytes) definition


SizeInt  =  LongInt


Signed integer type which fits for sizes



                                                                1195

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
SizeUInt  =  DWord


Unsigned Integer type which fits for sizes


TAbstractErrorProc  =  procedure


Abstract error handler procedural type.


TAllocateThreadVarsHandler  =  procedure


Threadvar allocation callback type for TThreadManager (1205   ).


TAnsiChar  =  Char


Alias for 1-byte sized char.


TAssertErrorProc  =  procedure(const  msg:  ShortString;
                                               const  fname:  ShortString;lineno:  LongInt;
                                               erroraddr:  pointer)


Assert error handler procedural type.


TBackTraceStrFunc  =  function(Addr:  Pointer)  :  ShortString


Type for formatting of backtrace dump.


TBasicEventCreateHandler  =  function(EventAttributes:  Pointer;
                                                           AManualReset:  Boolean;
                                                           InitialState:  Boolean;
                                                           const  Name:  ansistring)
                                                             :  PEventState


callback type for creating eventstate in TThreadManager (1205   ).


TBasicEventHandler  =  procedure(state:  PEventState)


Generic callback type for handling eventstate in TThreadManager (1205   ).


TBasicEventWaitForHandler  =  function(timeout:  Cardinal;
                                                             state:  PEventState)  :  LongInt


Wait for basic event callback type for TThreadManager (1205   ).


TBeginThreadHandler  =  function(sa:  Pointer;stacksize:  PtrUInt;
                                                   ThreadFunction:  TThreadFunc;p:  pointer;
                                                   creationFlags:  DWord;
                                                   var  ThreadId:  TThreadID)  :  TThreadID


Callback for thread start in TThreadManager (1205   ).


TBoundArray  =  Array  of  SizeInt



                                                                1196

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Dynamic array of integer.


tcalldesc  =  packed  record
   calltype  :  Byte;
   argcount  :  Byte;
   namedargcount  :  Byte;
   argtypes  :  Array[0..255]  of  Byte;
end
tcalldesc is used to encode the arguments to a dispatch call to an OLE dual interface.  It
is used on windows only.  It describes the arguments to a call.


TClass  =  Class  of  TObject


Class of TObject (1346   ).


TCriticalSectionHandler  =  procedure(var  cs)


Generic callback type for critical section handling in TThreadManager (1205   ).


TCtrlBreakHandler  =  function(CtrlBreak:  Boolean)  :  Boolean


TCtrlBreakHandler is the prototype for the CTRL-C handler.  If  CtrlBreak is True then
Ctrl-Break  was  hit,  otherwise  CTRL-C  was  hit.  The  handlers  should  return  True  to  signal
that the key-combination was handled.  If  False is returned, then default handling will be
used, which by default means an exception will be raised if the sysutils unit is used.


TDateTime  =  Double


Encoded Date-Time type.


tdispdesc  =  packed  record
   dispid  :  LongInt;
   restype  :  Byte;
   calldesc  :  tcalldesc;
end
tcalldesc  is  used  to  encode  a  dispatch  call  to  an  OLE  dispatch  interface.   It  is  used  on
windows only.  It describes the dispath call call.


tdynarrayindex  =  SizeInt


A variable of type tdynarrayindex will always have the correct size, suitable for serving as
an index in a dynamic array.


tdynarraytypeinfo  =  packed  record
   kind  :  Byte;
   namelen  :  Byte;
   elesize  :  SizeInt;
   eletype  :  pdynarraytypeinfo;
   vartype  :  LongInt;
end

                                                                1197

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
tdynarraytypeinfo  describes  the  structure  of  a  multi-dimensional  dynamical  array.  It  is
used in the DynArraySetLength (1236   ) call.


TEndThreadHandler  =  procedure(ExitCode:  DWord)


Callback for thread end in TThreadManager (1205   ).


TEntryInformation  =  record
   InitFinalTable  :  Pointer;
   ThreadvarTablesTable  :  Pointer;
   asm_exit  :  procedure;
   PascalMain  :  procedure;
   valgrind_used  :  Boolean;
end
TEntryInformation  is  used  to  initialize  a  Free  Pascal  program  or  library.  Under  normal
circumstances,  there  should  be  no  need  to  use  this  structure  directly:   it  is  used  by  the
system unit and special linking units.


TError  =  LongInt


Error type, used in variants.


TErrorProc  =  procedure(ErrNo:  LongInt;Address:  Pointer;Frame:  Pointer)


Standard error handler procedural type.


TExceptObject  =  record
   FObject  :  TObject;
   Addr  :  pointer;
   Next  :  PExceptObject;
   refcount  :  LongInt;
   Framecount  :  LongInt;
   Frames  :  PPointer;
end
TExceptObject is the exception description record which is found on the exception stack.


TExceptProc  =  procedure(Obj:  TObject;Addr:  Pointer;FrameCount:  LongInt;
                                       Frame:  PPointer)


Exception handler procedural type


TextFile  =  Text


Alias for Text file type.


TFPCHeapStatus  =  record
   MaxHeapSize  :  PtrInt;
   MaxHeapUsed  :  PtrInt;



                                                                1198

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
   CurrHeapSize  :  PtrInt;
   CurrHeapUsed  :  PtrInt;
   CurrHeapFree  :  PtrInt;
end
TFPCHeapStatus describes the state of the FPC heap manager.  This is not equivalent to the
THeapStatus  (1199   )  record  defined  by  Delphi,  which  contains  information  not  meaningful
for  the  FPC  heap  manager.  The  heap  status  can  be  retrieved  by  the  GetFPCHeapStatus
(1250   ) call.


TGetCurrentThreadIdHandler  =  function  :  TThreadID


Callback type for retrieving thread ID in TThreadManager (1205   ).


TGuid  =  packed  record
end
Standard GUID representation type.


THandle  =  LongInt


This type should be considered opaque.  It is used to describe file and other handles.


THeapStatus  =  record
   TotalAddrSpace  :  Cardinal;
   TotalUncommitted  :  Cardinal;
   TotalCommitted  :  Cardinal;
   TotalAllocated  :  Cardinal;
   TotalFree  :  Cardinal;
   FreeSmall  :  Cardinal;
   FreeBig  :  Cardinal;
   Unused  :  Cardinal;
   Overhead  :  Cardinal;
   HeapErrorCode  :  Cardinal;
end
THeapStatus is the record describing the current heap status.  It is returned by the GetH-
eapStatus (1250   ) call.


TInitThreadVarHandler  =  procedure(var  offset:  DWord;size:  DWord)


Threadvar initialization callback type for TThreadManager (1205   ).


TInterfacedClass  =  Class  of  TInterfacedObject


TInterfacedClass is a descendent of


tinterfaceentry  =  record
   IID  :  PGuid;



                                                                1199

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
   VTable  :  Pointer;
   IOffset  :  PtrInt;
   IIDStr  :  PShortString;
end
tinterfaceentry is used to store the list of Interfaces of a class.  This list is stored as an
array of  tinterfaceentry records.


tinterfaceentrytype  =  (etStandard,etVirtualMethodResult,
                                     etStaticMethodResult,etFieldValue)
                     Table 29.7:  Enumeration values for type tinterfaceentrytype


                                 __Value______________________________Explanation_____________
                                   etFieldValue                        Field value
                                   etStandard                          Standard entry
                                   etStaticMethodResult                Statis method
                                   etVirtualMethodResult               Virtual method
This is an internal type for the compiler to encode calls to dispatch interfaces.


tinterfacetable  =  record
   EntryCount  :  PtrInt;
   Entries  :  Array[0..0]  of  tinterfaceentry;
end
Record to store list of interfaces of a class.


TMemoryManager  =  record
   NeedLock  :  Boolean;
   Getmem  :  function(Size:  PtrInt)  :  Pointer;
   Freemem  :  function(p:  pointer)  :  PtrInt;
   FreememSize  :  function(p:  pointer;Size:  PtrInt)  :  PtrInt;
   AllocMem  :  function(Size:  PtrInt)  :  Pointer;
   ReAllocMem  :  function(var  p:  pointer;Size:  PtrInt)  :  Pointer;
   MemSize  :  function(p:  pointer)  :  PtrInt;
   GetHeapStatus  :  function  :  THeapStatus;
   GetFPCHeapStatus  :  function  :  TFPCHeapStatus;
end
TMemoryManager describes the memory manager.  For more information about the memory
manager, see the programmer's reference.


TMemoryMutexManager  =  record
   MutexInit  :  procedure;
   MutexDone  :  procedure;
   MutexLock  :  procedure;
   MutexUnlock  :  procedure;
end

                                                                1200

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
When the heapmanager needs a lock, then the mutex manager is used to handle the lock.


TMethod  =  record
   Code  :  Pointer;
   Data  :  Pointer;
end
TMethod  describes  a  general  method  pointer,  and  is  used  in  Run-Time  Type  Information
handling.


TMsgStrTable  =  record
   name  :  PShortString;
   method  :  pointer;
end
Record used in string message handler table.


TPCharArray  =  packed  Array[0..(MaxLongintdivSizeOf(PChar))-1]  of  PChar


Array of PChar


TProcedure  =  procedure


Simple procedural type.


TReleaseThreadVarsHandler  =  procedure


Threadvar release callback type for TThreadManager (1205   ).


TRelocateThreadVarHandler  =  function(offset:  DWord)  :  pointer


Threadvar relocalization callback type for TThreadManager (1205   ).


TResourceHandle  =  Cardinal


This is an opaque type.


TRTLCreateEventHandler  =  function  :  PRTLEvent


Callback type for creating a TRTLEvent type in TThreadManager (1205   ).


TRTLCriticalSection  =  Opaque  type


TRTLCriticalSection represents a critical section (a mutex).  This is an opaque type, it can
differ from operating system to operating system.  No assumptions should be made about
it's structure or contents.


TRTLEventHandler  =  procedure(AEvent:  PRTLEvent)
                                                                1201

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
Generic TRTLEvent handling type for TThreadManager (1205   ).


TRTLEventHandlerTimeout  =  procedure(AEvent:  PRTLEvent;timeout:  LongInt)


TRTLEvent timeout handling type for TThreadManager (1205   ).


TRTLEventSyncHandler  =  procedure(m:  trtlmethod;p:  TProcedure)


Callback type for event sycnhronization in TThreadManager (1205   ).


trtlmethod  =  procedure  of  object


Callback type for synchronization event.


TRuntimeError  =  (reNone,reOutOfMemory,reInvalidPtr,reDivByZero,
                            reRangeError,reIntOverflow,reInvalidOp,reZeroDivide,
                            reOverflow,reUnderflow,reInvalidCast,reAccessViolation,
                            rePrivInstruction,reControlBreak,reStackOverflow,
                            reVarTypeCast,reVarInvalidOp,reVarDispatch,
                            reVarArrayCreate,reVarNotArray,reVarArrayBounds,
                            reAssertionFailed,reExternalException,reIntfCastError,
                            reSafeCallError,reQuit,reCodesetConversion)


TRuntimeError is used in the Error (1239   ) procedure to indicate what kind of error should
be reported.


TSafeCallErrorProc  =  procedure(error:  HRESULT;addr:  pointer)


Prototype  of  a  safecall  error  handler  routine.   Error  is  the  error  number  (passed  by  the
Windows operating system) and Addr is the address where the error occurred.


TSemaphoreDestroyHandler  =  procedure(const  sem:  Pointer)


TSemaphoreDestroyHandler is the function prototype to destroy an existing semaphore, as
returned by (ThreadManager.SemaphoreInit).  It is used by the thread manager (ThreadManager.SemaphoreDestroy)


TSemaphorePostHandler  =  procedure(const  sem:  Pointer)


TSemaphorePostHandler  is  the  function  prototype  to  post  an  event  to  the  semaphore.  It
should handle a pointer as returned by the ThreadManager.SemaphoreInit procedure.  it's
used by the thread manager ThreadManager.SemaphorePost.


TSemaphoreWaitHandler  =  procedure(const  sem:  Pointer)


TSemaphoreWaitHandler  is  the  function  prototype  to  wait  on  an  event  on  the  semaphore
(which should be posted to the semaphore with ThreadManager.SemaphorePost).  It should
handle a pointer as eturned by the ThreadManager.SemaphoreInit procedure.  it's used by
the thread manager ThreadManager.SemaphoreWait.


TSempahoreInitHandler  =  function  :  Pointer
                                                                1202

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___

                        Table 29.8:  Enumeration values for type TRuntimeError


                       __Value____________________________Explanation__________________________________
                         reAccessViolation                Access Violation
                         reAssertionFailed                Assertion failed error
                         reCodesetConversion              Code set conversion error
                         reControlBreak                   User pressed CTRL-C
                         reDivByZero                      Division by zero error
                         reExternalException              An external exception occurred
                         reIntfCastError                  Interface typecast error
                         reIntOverflow                    Integer overflow error
                         reInvalidCast                    Invalid (class) typecast error
                         reInvalidOp                      Invalid operation error
                         reInvalidPtr                     Invalid pointer error
                         reNone                           No error
                         reOutOfMemory                    Out of memory error
                         reOverflow                       Overflow error
                         rePrivInstruction                Privileged instruction error
                         reQuit                           Quit signal error
                         reRangeError                     Range check error
                         reSafeCallError                  Safecall (IDispInterface) error
                         reStackOverflow                  Stack overflow error
                         reUnderflow                      Underflow error
                         reVarArrayBounds                 Variant array bounds error
                         reVarArrayCreate                 Variant array creation error
                         reVarDispatch                    Variant Dispatch error.
                         reVarInvalidOp                   Invalid variant operation error
                         reVarNotArray                    Variant is not an array error.
                         reVarTypeCast                    Invalid typecase from variant
                         reZeroDivide                     Division by zero error

TSempahoreInitHandler is the function prototype for initializing a semaphore.  It is used by
the thread manager (ThreadManager.SemaphoreInit) to create semaphores.  The function
should return a pointer, usable by the other semaphore functions of the thread manager.


TStringMessageTable  =  record
   count  :  PtrInt;
   msgstrtable  :  Array[0..0]  of  TMsgStrTable;
end
Record  used  to  describe  the  string  messages  handled  by  a  class.   It  consists  of  a  count,
followed by an array of TMsgStrTable (1201   ) records.


TTextLineBreakStyle  =  (tlbsLF,tlbsCRLF,tlbsCR)


Text line break style.  (end of line character)


TThreadFunc  =  function(parameter:  pointer)  :  PtrInt


Thread function prototype



                                                                1203

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___

                    Table 29.9:  Enumeration values for type TTextLineBreakStyle


                 __Value____________Explanation_______________________________________________________________
                   tlbsCR            Carriage-return (#13, Mac-OS style)
                   tlbsCRLF          Carriage-return, line-feed (#13#30, Windows style)
                   tlbsLF            Line-feed only (#10, unix style)

TThreadGetPriorityHandler  =  function(threadHandle:  TThreadID)  :  LongInt


Callback type for thread priority getting in TThreadManager (1205   ).


TThreadHandler  =  function(threadHandle:  TThreadID)  :  DWord


Generic thread handler callback for TThreadManager (1205   ).


TThreadID  =  PtrUInt


This is an opaque type, it can differ from operating system to operating system.


TThreadManager  =  record
   InitManager  :  function  :  Boolean;
   DoneManager  :  function  :  Boolean;
   BeginThread  :  TBeginThreadHandler;
   EndThread  :  TEndThreadHandler;
   SuspendThread  :  TThreadHandler;
   ResumeThread  :  TThreadHandler;
   KillThread  :  TThreadHandler;
   ThreadSwitch  :  TThreadSwitchHandler;
   WaitForThreadTerminate  :  TWaitForThreadTerminateHandler;
   ThreadSetPriority  :  TThreadSetPriorityHandler;
   ThreadGetPriority  :  TThreadGetPriorityHandler;
   GetCurrentThreadId  :  TGetCurrentThreadIdHandler;
   InitCriticalSection  :  TCriticalSectionHandler;
   DoneCriticalSection  :  TCriticalSectionHandler;
   EnterCriticalSection  :  TCriticalSectionHandler;
   LeaveCriticalSection  :  TCriticalSectionHandler;
   InitThreadVar  :  TInitThreadVarHandler;
   RelocateThreadVar  :  TRelocateThreadVarHandler;
   AllocateThreadVars  :  TAllocateThreadVarsHandler;
   ReleaseThreadVars  :  TReleaseThreadVarsHandler;
   BasicEventCreate  :  TBasicEventCreateHandler;
   BasicEventDestroy  :  TBasicEventHandler;
   BasicEventResetEvent  :  TBasicEventHandler;
   BasicEventSetEvent  :  TBasicEventHandler;
   BasiceventWaitFOr  :  TBasicEventWaitForHandler;
   RTLEventCreate  :  TRTLCreateEventHandler;
   RTLEventDestroy  :  TRTLEventHandler;
   RTLEventSetEvent  :  TRTLEventHandler;
   RTLEventResetEvent  :  TRTLEventHandler;
   RTLEventWaitFor  :  TRTLEventHandler;
   RTLEventSync  :  TRTLEventSyncHandler;



                                                                1204

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
   RTLEventWaitForTimeout  :  TRTLEventHandlerTimeout;
   SemaphoreInit  :  TSempahoreInitHandler;
   SemaphoreDestroy  :  TSemaphoreDestroyHandler;
   SemaphorePost  :  TSemaphorePostHandler;
   SemaphoreWait  :  TSemaphoreWaitHandler;
end
TThreadManager is a record that contains all callbacks needed for the thread handling rou-
tines  of  the  Free  Pascal  Run-Time  Library.   The  thread  manager  can  be  set  by  the  Set-
ThreadManager  (1320   )  procedure,  and  the  current  thread  manager  can  be  retrieved  with
the GetThreadManager (1252   ) procedure.

The Windows RTL will set the thread manager automatically to a system thread manager,
based on the Windows threading routines.  Unix operating systems provide a unit cthreads
which implements threads based on the C library POSIX thread routines.  It is not included
by default, because it would make the system unit dependent on the C library.

For more information about thread programming, see the programmer's guide.


TThreadSetPriorityHandler  =  function(threadHandle:  TThreadID;
                                                             Prio:  LongInt)  :  Boolean


Callback type for thread priority setting in TThreadManager (1205   ).


TThreadSwitchHandler  =  procedure


Callback type for thread switch in TThreadManager (1205   ).


TUCS4CharArray  =  Array[0..$effffff]  of  UCS4Char


Array of UCS4Char (1208   ) characters.


tvararray  =  record
   dimcount  :  Word;
   flags  :  Word;
   elementsize  :  LongInt;
   lockcount  :  LongInt;
   data  :  pointer;
   bounds  :  tvararrayboundarray;
end
tvararray  is  a  record  describing  a  variant  array.  It  contains  some  general  data,  followed
by a number of TVarArrayBound (1205   ) records equal to the number of dimensions in the
array (dimcoun).


tvararraybound  =  record
   elementcount  :  LongInt;
   lowbound  :  LongInt;
end
tvararraybound is used to describe one dimension in a variant array.



                                                                1205

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
tvararrayboundarray  =  Array[0..0]  of  tvararraybound


array of tvararraybound (1205   ) records.


tvararraycoorarray  =  Array[0..0]  of  LongInt


Array of variant array coordinates


tvardata  =  packed  record
   vtype  :  tvartype;
end
TVarData  is  a  record  representation  of  a  variant.   It  contains  the  internal  structure  of  a
variant and is handled by the various variant handling routines.


tvariantmanager  =  record
   vartoint  :  function(const  v:  variant)  :  LongInt;
   vartoint64  :  function(const  v:  variant)  :  Int64;
   vartoword64  :  function(const  v:  variant)  :  qword;
   vartobool  :  function(const  v:  variant)  :  Boolean;
   vartoreal  :  function(const  v:  variant)  :  extended;
   vartotdatetime  :  function(const  v:  variant)  :  TDateTime;
   vartocurr  :  function(const  v:  variant)  :  currency;
   vartopstr  :  procedure(var  s;const  v:  variant);
   vartolstr  :  procedure(var  s:  ansistring;const  v:  variant);
   vartowstr  :  procedure(var  s:  widestring;const  v:  variant);
   vartointf  :  procedure(var  intf:  IInterface;const  v:  variant);
   vartodisp  :  procedure(var  disp:  IDispatch;const  v:  variant);
   vartodynarray  :  procedure(var  dynarr:  pointer;const  v:  variant;typeinfo:  pointer);
   varfrombool  :  procedure(var  dest:  variant;const  source:  Boolean);
   varfromint  :  procedure(var  dest:  variant;const  source:  LongInt;const  Range:  LongInt);
   varfromint64  :  procedure(var  dest:  variant;const  source:  Int64);
   varfromword64  :  procedure(var  dest:  variant;const  source:  qword);
   varfromreal  :  procedure(var  dest:  variant;const  source:  extended);
   varfromtdatetime  :  procedure(var  dest:  Variant;const  source:  TDateTime);
   varfromcurr  :  procedure(var  dest:  Variant;const  source:  Currency);
   varfrompstr  :  procedure(var  dest:  variant;const  source:  ShortString);
   varfromlstr  :  procedure(var  dest:  variant;const  source:  ansistring);
   varfromwstr  :  procedure(var  dest:  variant;const  source:  WideString);
   varfromintf  :  procedure(var  dest:  variant;const  source:  IInterface);
   varfromdisp  :  procedure(var  dest:  variant;const  source:  IDispatch);
   varfromdynarray  :  procedure(var  dest:  variant;const  source:  pointer;typeinfo:  pointer);
   olevarfrompstr  :  procedure(var  dest:  olevariant;const  source:  shortstring);
   olevarfromlstr  :  procedure(var  dest:  olevariant;const  source:  ansistring);
   olevarfromvar  :  procedure(var  dest:  olevariant;const  source:  variant);
   olevarfromint  :  procedure(var  dest:  olevariant;const  source:  LongInt;
                   const  range:  ShortInt);
   varop  :  procedure(var  left:  variant;const  right:  variant;opcode:  tvarop);
   cmpop  :  function(const  left:  variant;const  right:  variant;const  opcode:  tvarop)
                   :  Boolean;
   varneg  :  procedure(var  v:  variant);
   varnot  :  procedure(var  v:  variant);



                                                                1206

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
   varinit  :  procedure(var  v:  variant);
   varclear  :  procedure(var  v:  variant);
   varaddref  :  procedure(var  v:  variant);
   varcopy  :  procedure(var  dest:  variant;const  source:  variant);
   varcast  :  procedure(var  dest:  variant;const  source:  variant;vartype:  LongInt);
   varcastole  :  procedure(var  dest:  variant;const  source:  variant;vartype:  LongInt);
   dispinvoke  :  procedure(dest:  pvardata;const  source:  tvardata;calldesc:  pcalldesc;
                   params:  pointer);
   vararrayredim  :  procedure(var  a:  variant;highbound:  SizeInt);
   vararrayget  :  function(const  a:  variant;indexcount:  SizeInt;indices:  PSizeInt)
                   :  variant;
   vararrayput  :  procedure(var  a:  variant;const  value:  variant;indexcount:  SizeInt;
                   indices:  PSizeInt);
   writevariant  :  function(var  t:  text;const  v:  variant;width:  LongInt)  :  Pointer;
   write0Variant  :  function(var  t:  text;const  v:  Variant)  :  Pointer;
end
TVariantManager  describes  the  variant  manager  as  expected  by  the  SetVariantManager
(1320   ) call.


tvarop  =  (opadd,opsubtract,opmultiply,opdivide,opintdivide,opmodulus,
                opshiftleft,opshiftright,opand,opor,opxor,opcompare,opnegate,
                opnot,opcmpeq,opcmpne,opcmplt,opcmple,opcmpgt,opcmpge,oppower)
                             Table 29.10:  Enumeration values for type tvarop


                 __Value_______________Explanation___________________________________________________________
                   opadd               Variant operation:  Addition.
                   opand               Variant operation:  Binary AND operation
                   opcmpeq             Variant operation:  Compare equal.
                   opcmpge             Variant operation:  Compare larger than or equal
                   opcmpgt             Variant operation:  Compare larger than
                   opcmple             Variant operation:  Compare less than or equal to
                   opcmplt             Variant operation:  Compare less than.
                   opcmpne             Variant operation:  Compare not equal
                   opcompare           Variant operation:  Compare
                   opdivide            Variant operation:  division
                   opintdivide         Variant operation:  integer divide
                   opmodulus           Variant operation:  Modulus
                   opmultiply          Variant operation:  multiplication
                   opnegate            Variant operation:  negation.
                   opnot               Variant operation:  Binary NOT operation.
                   opor                Variant operation:  Binary OR operation
                   oppower             Variant operation:  Power
                   opshiftleft         Variant operation:  Shift left
                   opshiftright        Variant operation:  Shift right
                   opsubtract          Variant operation:  Substraction
                   opxor               Variant operation:  binary XOR operation.
tvarop describes a variant operation.  It is mainly used for the variant manager to implement
the various conversions and mathematical operations on a variant.



                                                                1207

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
TVarRec  =  record
end
TVarRec is a record generated by the compiler for each element in a array  of  const call.
The procedure that receives the constant array receives an array of  TVarRec elements, with
lower bound zero and high bound equal to the number of elements in the array minus one
(as returned by High(Args))


tvartype  =  Word


Type with size of variant type.


TWaitForThreadTerminateHandler  =  function(threadHandle:  TThreadID;
                                                                     TimeoutMs:  LongInt)  :  DWord


Callback type for thread termination in TThreadManager (1205   ).


TWideStringManager  =  record
   Wide2AnsiMoveProc  :  procedure(source:  PWideChar;var  dest:  ansistring;len:  SizeInt);
   Ansi2WideMoveProc  :  procedure(source:  PChar;var  dest:  widestring;len:  SizeInt);
   UpperWideStringProc  :  function(const  S:  WideString)  :  WideString;
   LowerWideStringProc  :  function(const  S:  WideString)  :  WideString;
   CompareWideStringProc  :  function(const  s1:  WideString;const  s2:  WideString)  :  PtrInt;
   CompareTextWideStringProc  :  function(const  s1:  WideString;const  s2:  WideString)  :  PtrInt;
   CharLengthPCharProc  :  function(const  Str:  PChar)  :  PtrInt;
   UpperAnsiStringProc  :  function(const  s:  ansistring)  :  ansistring;
   LowerAnsiStringProc  :  function(const  s:  ansistring)  :  ansistring;
   CompareStrAnsiStringProc  :  function(const  S1:  ansistring;const  S2:  ansistring)  :  PtrInt;
   CompareTextAnsiStringProc  :  function(const  S1:  ansistring;const  S2:  ansistring)  :  PtrInt;
   StrCompAnsiStringProc  :  function(S1:  PChar;S2:  PChar)  :  PtrInt;
   StrICompAnsiStringProc  :  function(S1:  PChar;S2:  PChar)  :  PtrInt;
   StrLCompAnsiStringProc  :  function(S1:  PChar;S2:  PChar;MaxLen:  PtrUInt)  :  PtrInt;
   StrLICompAnsiStringProc  :  function(S1:  PChar;S2:  PChar;MaxLen:  PtrUInt)  :  PtrInt;
   StrLowerAnsiStringProc  :  function(Str:  PChar)  :  PChar;
   StrUpperAnsiStringProc  :  function(Str:  PChar)  :  PChar;
   ThreadInitProc  :  procedure;
   ThreadFiniProc  :  procedure;
end
TWideStringManager contains the definition of the widestring manager.


UCS2Char  =  WideChar


UCS2 unicode character.


UCS4Char  =


UCS unicode character (unsigned 32 bit word)


UCS4String  =  Array  of  UCS4Char



                                                                1208

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
String of UCS4Char (1208   ) characters.


UInt64  =  QWord


Unsigned 64-bit integer


UTF8String  =  ansistring


UTF-8 unicode (ansi) string.


ValSInt  =  LongInt


Integer with the same size as the return code of the Val (1337   ) function.


ValUInt  =  Cardinal


Integer with the same size as the return code of the Val (1337   ) function.


WChar  =  Widechar


Wide char (16-bit sized char)
29.8.3         Variables

argc  :  LongInt;external  name  operatingsystem_parameter_argc


argc contains the number of command-line arguments passed to the program by the OS. It
is not available on all systems.


argv  :  PPChar;external  name  operatingsystem_parameter_argv


argv contains a pointer to a nil-terminated array of null-terminated strings, containing the
command-line arguments passed to the program by the OS. It is not available on all systems.


cmdline  :  PChar  =  nil


Current command-line.


DispCallByIDProc  :  pointer


VarDispProc is called by the compiler if it needs to perform an interface call from a variant
which contains a dispatch interface.  For instance, the following call:


Var
    V  :  OleVariant;
begin
    (V  as  IWord).OpenDocument('c:\temp\mydoc.doc');
end;


where IWord is a dispatch interface is encoded by the compiler and passed to DispCallByIDProc.

This pointer must be set by a routine that calls the OS COM handling routines.



                                                                1209

__________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___
envp  :  PPChar;external  name  operatingsystem_parameter_envp


envp contains a pointer to a nil-terminated array of null-terminated strings, containing the
environment variables passed to the program by the OS. It is not available on all systems.


ErrOutput  :  Text


ErrOutput is provided for Delphi compatibility.


ExitCode  :  LongInt;public  name  operatingsystem_result


Exit code for the program, will be communicated to the OS on exit.


fpc_threadvar_relocate_proc  :  pointer;public  name  FPC_THREADVAR_RELOCATE
InOutRes  :  Word


Result of last I/O operation.  Read-Only.


Input  :  Text


Standard input text file.


IsConsole  :  Boolean


True for console applications, False for GUI applications.


IsLibrary  :  Boolean  =  false


True if the current module is a library.  Otherwise module is an excutable


Output  :  Text


Standard output text file.


RandSeed  :  Cardinal


Seed for Random (1303   ) function.


ReturnNilIfGrowHeapFails  :  Boolean


ReturnNilIfGrowHeapFails describes what happens if there is no more memory available
from the operating system.  if set to True the memory manager will return Nil.  If set to
False then a run-time error will occur.


softfloat_exception_flags  :  Byte


Current soft float exception flags


softfloat_exception_mask  :  Byte



                                                                1210

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                Current soft float exception mask


                StackBottom  :  Pointer


                Current stack bottom.


                StackLength  :  SizeUInt


                Maximum stack length.


                StackTop  :  Pointer


                StackTop contains the top of the stack for the current process.  It is used to check the heap
                on some operating systems, and is set by the system unit initialization code.  Do not use or
                modify this value.


                StdErr  :  Text


                Standard diagnostic output text file.


                StdOut  :  Text


                Alias for Output (1210   ).


                ThreadID  :  TThreadID


                Current Thread ID.


                widestringmanager  :  TWideStringManager


                Contains the current widestring manager.  Do not use directly.
                29.9          Procedures  and  functions



                29.9.1         abs

    Synopsis:    Calculate absolute value

Declaration:     function  abs(l:  LongInt)  :  LongInt
                function  abs(l:  Int64)  :  Int64
                function  abs(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Abs returns the absolute value of a variable.  The result of the function has the same type
                as its argument, which can be any numerical type.

       Errors:   None.

    See also:    Round (1311   )


                Listing:  ./refex/ex1.pp



                                                                                1211

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  d e m o n s t r a t et h e  Abs    f u n c t i o n. }


                Var
                    r   :  r e a l;
                    i   :  i n t e g e r;


                 b e g i n
                    r := abs   ( - 1 . 0 ) ;    {  r : = 1 . 0 }
                    i := abs   ( - 2 1 ) ;      {   i: = 2 1  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.2         AbstractError

    Synopsis:    Generate an abstract error.

Declaration:     procedure  AbstractError

    Visibility:   default

Description:     AbstractError generates an abstract error (run-time error 211).  If the AbstractErrorProc
                (1167   ) constant is set, it will be called instead.

       Errors:   This routine causes a run-time error 211.

    See also:    AbstractErrorProc (1167   )
                29.9.3         AcquireExceptionObject

    Synopsis:    Obtain a reference to the current exception object

Declaration:     function  AcquireExceptionObject  :  Pointer

    Visibility:   default

Description:     AcquireExceptionObject returns the current exception object.  It raises the reference count
                of the exception object, so it will not be freed.  Calling this method is only valid within an
                except block.

                The effect of this function is countered by re-raising an exception via raise;

                To make sure that the exception object is released when it is no longer needed, ReleaseEx-
                ceptionObject (1308   ) must be called when the reference is no longer needed.

       Errors:   If there is no current exception, a run-time error 231 will occur.

    See also:    ReleaseExceptionObject (1308   )
                29.9.4         AddExitProc

    Synopsis:    Add an exit procedure to the exit procedure chain.

Declaration:     procedure  AddExitProc(Proc:  TProcedure)

    Visibility:   default

                                                                                1212

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     AddExitProc adds Proc to the exit procedure chain.  At program exit, all procedures added
                in this way will be called in reverse order.

       Errors:   None.

    See also:    ExitProc (1170   )
                29.9.5         Addr

    Synopsis:    Return address of a variable

Declaration:     function  Addr(X:  TAnytype)  :  Pointer

    Visibility:   default

Description:     Addr returns a pointer to its argument, which can be any type, or a function or procedure
                name.  The returned pointer isn't typed.  The same result can be obtained by the @ operator,
                which can return a typed pointer (\progref).

       Errors:   None

    See also:    SizeOf (1322   )


                Listing:  ./refex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;


                {   Program       t o  d e m o n s t r a t et h e  Addr     f u n c t i o n. }


                Const      Z e r o  :  i n t e g e r =  0 ;


                Var    p   :   p o i n t e r;
                        i  :   I n t e g e r;


                 b e g i n
                    p := Addr   ( p ) ;         {  P   p o i n t s t o   i t s e l f}
                    p := Addr   ( I ) ;         {  P   p o i n t s t o  I   }
                    p := Addr   ( Z e r o) ;    {  P   p o i n t s t o   'Zero   '  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.6         Align

    Synopsis:    Return aligned version of an address

Declaration:     function  Align(Addr:  PtrUInt;Alignment:  PtrUInt)  :  PtrUInt
                function  Align(Addr:  Pointer;Alignment:  PtrUInt)  :  Pointer

    Visibility:   default

Description:     Align returns Address, aligned to Alignment bytes.

       Errors:   None.
                                                                                1213

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.7         AllocMem

    Synopsis:    Allocate and clear memory.

Declaration:     function  AllocMem(Size:  PtrInt)  :  pointer

    Visibility:   default

Description:     AllocMem calls getmem GetMem (1251   ), and clears the allocated memory, i.e.  the allocated
                memory is filled with Size zero bytes.

    See also:    GetMem (1251   )
                29.9.8         AnsiToUtf8

    Synopsis:    Convert ansi string to UTF-8 string

Declaration:     function  AnsiToUtf8(const  s:  ansistring)  :  UTF8String

    Visibility:   default

Description:     AnsiToUtf8 converts the ansistring S to a WideString in UTF-8 format.

       Errors:   None.

    See also:    Utf8toAnsi (1336   )
                29.9.9         Append

    Synopsis:    Open a file in append mode

Declaration:     procedure  Append(var  t:  Text)

    Visibility:   default

Description:     Append opens an existing file in append mode.  Any data written to F will be appended to
                the file.  Only text files can be opened in append mode.  After a call to Append,  the file F
                becomes write-only.  File sharing is not taken into account when calling Append.

       Errors:   If the file doesn't exist when appending, a run-time error will be generated.  This behaviour
                has changed on Windows and Linux platforms, where in versions prior to 1.0.6, the file would
                be created in append mode.

    See also:    Rewrite (1310   ), Close (1223   ), Reset (1308   )


                Listing:  ./refex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  d e m o n s t r a t et h e  Append      f u n c t i o n.  }


                Var     f  :   t e x t;


                 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 ) ;                     {   f i l e i s  o p e n e d  f o r  w r i t e,  and    e m p t i e d}
                    W r i t e l n (F  , 'T h i s  i s  t h e  f i r s t  l i n e o f  t e x t. t x t ') ;
                    c l o s e ( f ) ;
                    Append    ( f ) ;                         {   f i l e i s  o p e n e d  f o r  w r i t e,  b u t NOT     e m p *
 *t i e d.
                                                                 any    t e x t  w r i t t e n t o  i t   i s  a p p e n d e d.}



                                                                                1214

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    W r i t e l n ( f , 'T h i s  i s  t h e  s e c o n d l i n e  o f  t e x t. t x t' ) ;
                    c l o s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.10          arctan

    Synopsis:    Calculate inverse tangent

Declaration:     function  arctan(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Arctan returns the Arctangent of  X, which can be any Real type.  The resulting angle is in
                radial units.

       Errors:   None

    See also:    Sin (1321   ), Cos (1231   )


                Listing:  ./refex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  d e m o n s t r a t et h e  ArcTan      f u n c t i o n.  }


                Var    R   :   R e a l;


                 b e g i n
                    R := ArcTan     ( 0 ) ;          {  R : = 0  }
                    R := ArcTan     ( 1 ) /p i;      {  R : = 0 . 2 5 }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.11          ArrayStringToPPchar

    Synopsis:    Concert an array of string to an array of null-terminated strings

Declaration:     function  ArrayStringToPPchar(const  S:  Array  of  AnsiString;
                                                              reserveentries:  LongInt)  :  PPChar

    Visibility:   default

Description:     ArrayStringToPPchar creates an array of null-terminated strings that point to strings which
                are the same as the strings in the array S. The function returns a pointer to this array.  The
                array and the strings it contains must be disposed of after being used, because it they are
                allocated on the heap.

                The ReserveEntries parameter tells ArrayStringToPPchar to allocate room at the end of
                the array for another ReserveEntries entries.

       Errors:   If not enough memory is available, an error may occur.

    See also:    StringToPPChar (1326   )



                                                                                1215

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.12          Assert

    Synopsis:    Check validity of a given condition.

Declaration:     procedure  Assert(Expr:  Boolean)
                procedure  Assert(Expr:  Boolean;const  Msg:  String)

    Visibility:   default

Description:     With assertions on,  Assert tests if  expr is false,  and if so,  aborts the application with a
                Runtime error 227 and an optional error message in msg.  If  expr is true,  program execu-
                tion  continues  normally.   If  assertions  are  not  enabled  at  compile  time,  this  routine  does
                nothing,  and  no  code  is  generated  for  the  Assert  call.  Enabling  and  disabling  assertions
                at compile time is done via the \$C or \$ASSERTIONS compiler switches.  These are global
                switches.   The  default  behavior  of  the  assert  call  can  be  changed  by  setting  a  new  han-
                dler  in  the  AssertErrorProc  variable.   Sysutils  overrides  the  default  handler  to  raise  a
                EAssertionFailed exception.

       Errors:   None.

    See also:    Halt (1253   ), Runerror (1313   )
                29.9.13          Assign

    Synopsis:    Assign a name to a file

Declaration:     procedure  Assign(var  f:  File;const  Name:  String)
                procedure  Assign(var  f:  File;p:  PChar)
                procedure  Assign(var  f:  File;c:  Char)
                procedure  Assign(var  f:  TypedFile;const  Name:  String)
                procedure  Assign(var  f:  TypedFile;p:  PChar)
                procedure  Assign(var  f:  TypedFile;c:  Char)
                procedure  Assign(var  t:  Text;const  s:  String)
                procedure  Assign(var  t:  Text;p:  PChar)
                procedure  Assign(var  t:  Text;c:  Char)

    Visibility:   default

Description:     Assign assigns a name to F, which can be any file type.  This call doesn't open the file, it
                just assigns a name to a file variable, and marks the file as closed.

       Errors:   None.

    See also:    Reset (1308   ), Rewrite (1310   ), Append (1214   )


                Listing:  ./refex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n f u n c t i o n.  }


                Var    F   :   t e x t;


                 b e g i n
                    A s s i g n ( F , ' ') ;
                    R e w r i t e ( f ) ;
                    {  The     f o l l o w i n gc a n  be   p u t  i n  any     f i l e by   r e d i r e c t i n gi t
                       f r o m  t h e  command       l i n e. }
                    W r i t e l n ( f , 'T h i s  g o e s t o   s t a n d a r do u t p u t !  ') ;



                                                                                1216

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    C l o s e ( f ) ;
                    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  d o e s n'' t  go    t o  s t a n d a r d o u t p u t ! ') ;
                    c l o s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.14          Assigned

    Synopsis:    Check if a pointer is valid

Declaration:     function  Assigned(P:  Pointer)  :  Boolean

    Visibility:   default

Description:     Assigned returns True if P is non-nil and retuns False of P is nil.  The main use of Assigned
                is that Procedural variables, method variables and class-type variables also can be passed to
                Assigned.

       Errors:   None

    See also:    New (1273   )


                Listing:  ./refex/ex96.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 6;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n e d f u n c t i o n. }


                Var    P   :   P o i n t e r;


                 b e g i n
                    I f  Not    A s s i g n e d(P )  then
                        W r i t e l n(  'P o i n t e r i s   i n i t i a l l yNIL  ' ) ;
                    P := @P  ;
                    I f  Not    A s s i g n e d(P )  then
                        W r i t e l n('I n t e r n a l i n c o n s i s t e n c'y)
                    e l s e
                        W r i t e l n('A l l  i s   w e l l i n  FPC   ')
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.15          BasicEventCreate

    Synopsis:    Obsolete.  Don't use

Declaration:     function  BasicEventCreate(EventAttributes:  Pointer;
                                                         AManualReset:  Boolean;InitialState:  Boolean;
                                                         const  Name:  ansistring)  :  PEventState

    Visibility:   default

Description:     BasicEventCreate is obsolete, use RTLEventCreate (1312   ) instead.

    See also:    RTLEventCreate (1312   )



                                                                                1217

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.16          basiceventdestroy

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventdestroy(state:  PEventState)

    Visibility:   default

Description:     basiceventdestroy is obsolete.  Use RTLEventDestroy (1312   ) instead.

    See also:    RTLEventDestroy (1312   )
                29.9.17          basiceventResetEvent

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventResetEvent(state:  PEventState)

    Visibility:   default

Description:     basiceventResetEvent is obsolete.  Use RTLEventResetEvent (1312   ) instead.

    See also:    RTLEventResetEvent (1312   )
                29.9.18          basiceventSetEvent

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventSetEvent(state:  PEventState)

    Visibility:   default

Description:     basiceventSetEvent is obsolete.  Use RTLEventSetEvent (1312   ) instead.

    See also:    RTLEventSetEvent (1312   )
                29.9.19          basiceventWaitFor

    Synopsis:    Obsolete.  Don't use

Declaration:     function  basiceventWaitFor(Timeout:  Cardinal;state:  PEventState)
                                                             :  LongInt

    Visibility:   default

Description:     basiceventwaitfor is obsolete.  Use RTLEventWaitFor (1313   ) instead.

    See also:    RTLEventWaitFor (1313   )
                29.9.20          BeginThread

    Synopsis:    Start a new thread.

Declaration:     function  BeginThread(sa:  Pointer;stacksize:  SizeUInt;
                                                 ThreadFunction:  TThreadFunc;p:  pointer;
                                                 creationFlags:  DWord;var  ThreadId:  TThreadID)
                                                   :  TThreadID
                function  BeginThread(ThreadFunction:  TThreadFunc)  :  TThreadID



                                                                                1218

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                function  BeginThread(ThreadFunction:  TThreadFunc;p:  pointer)  :  TThreadID
                function  BeginThread(ThreadFunction:  TThreadFunc;p:  pointer;
                                                 var  ThreadId:  TThreadID)  :  TThreadID
                function  BeginThread(ThreadFunction:  TThreadFunc;p:  pointer;
                                                 var  ThreadId:  TThreadID;const  stacksize:  SizeUInt)
                                                  :  TThreadID

    Visibility:  default

Description:     BeginThread starts a new thread and executes ThreadFunction in the new thread.  If  P is
                specified, then it is passed to ThreadFunction.  If  ThreadId is specified, it is filled with the
                thread ID of the newly started thread.  If  StackSize is specified, it is set as the stack size
                for the new thread.  If none is specified, a default stack size of 32Kb is used.

                The function returns the thread ID on succes, or 0 if an error occurred.

       Errors:   On error, a nonzero value is returned.

    See also:    EndThread (1236   )
                29.9.21          BEtoN

    Synopsis:    Convert Big Endian-ordered integer to Native-ordered integer

Declaration:     function  BEtoN(const  AValue:  SmallInt)  :  SmallInt
                function  BEtoN(const  AValue:  Word)  :  Word
                function  BEtoN(const  AValue:  LongInt)  :  LongInt
                function  BEtoN(const  AValue:  DWord)  :  DWord
                function  BEtoN(const  AValue:  Int64)  :  Int64
                function  BEtoN(const  AValue:  QWord)  :  QWord

    Visibility:   default

Description:     BEToN will rearrange the bytes in a Big-Endian number to the native order for the current
                processor.   That  is,  for  a  big-endian  processor,  it  will  do  nothing,  and  for  a  little-endian
                processor, it will invert the order of the bytes.

    See also:    LEtoN (1268   ), NtoBE (1273   ), NtoLE (1273   )
                29.9.22          binStr

    Synopsis:    Convert integer to string with binary representation.

Declaration:     function  binStr(Val:  LongInt;cnt:  Byte)  :  shortstring
                function  binStr(Val:  Int64;cnt:  Byte)  :  shortstring
                function  binStr(Val:  qword;cnt:  Byte)  :  shortstring

    Visibility:   default

Description:     BinStr returns a string with the binary representation of  Value.  The string has at most
                cnt characters.  (i.e.  only the cnt rightmost bits are taken into account) To have a complete
                representation of any longint-type value, 32 bits are needed, i.e.  cnt=32

       Errors:   None.

    See also:    Str (1325   ), Val (1337   ), HexStr (1254   ), OctStr (1274   )


                Listing:  ./refex/ex82.pp



                                                                                1219

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 8 2;


                {   Program       t o  d e m o n s t r a t et h e  B i n S t r f u n c t i o n }


                Const      V a l u e =  4 5 6 7 8 ;


                Var     I  :   l o n g i n t;


                 b e g i n
                    For    I : = 8  t o  2 0  do
                        W r i t e l n( B i n S t r(V a l u e, I ) : 2 0 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.23          BlockRead

    Synopsis:    Read data from an untyped file into memory

Declaration:     procedure  BlockRead(var  f:  File;var  Buf;count:  Int64;var  Result:  Int64)
                procedure  BlockRead(var  f:  File;var  Buf;count:  LongInt;
                                                var  Result:  LongInt)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Cardinal;
                                                var  Result:  Cardinal)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Word;var  Result:  Word)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Word;var  Result:  Integer)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Int64)

    Visibility:   default

Description:     Blockread  reads  count  or  less  records  from  file  F.  A  record  is  a  block  of  bytes  with  size
                specified by the Rewrite (1310   ) or Reset (1308   ) statement.  The result is placed in Buffer,
                which must contain enough room for Count records.  The function cannot read partial records.
                If  Result  is  specified,  it  contains  the  number  of  records  actually  read.   If  Result  isn't
                specified, and less than Count records were read, a run-time error is generated.  This behavior
                can be controlled by the \var{\{\$i\}} switch.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Blockwrite (1221   ), Close (1223   ), Reset (1308   ), Assign (1216   )


                Listing:  ./refex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  d e m o n s t r a t et h e  B l o c k R e a dand     B l o c k W r i t ef u n c t i o n s. }


                Var    F i n ,  f o u t  :   F i l e;
                       NumRead      ,NumWritten          :  Word   ;
                       Buf     :  A r r a y[ 1 . . 2 0 4 8 ]o f  b y t e;
                        T o t a l :   L o n g i n t;


                 b e g i n
                    A s s i g n ( F i n,   Paramstr      ( 1 ) ) ;
                    A s s i g n ( Fout   , Paramstr      ( 2 ) ) ;
                    R e s e t ( F i n , 1 ) ;
                    R e w r i t e ( Fout   , 1 ) ;



                                                                                1220

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    T o t a l: = 0 ;
                    Repeat
                       BlockRead         ( F i n, b u f, S i z e o f(b u f) ,NumRead      ) ;
                       B l o c k W r i t e (Fout    ,Buf   ,NumRead     , NumWritten        ) ;
                        i n c(T o t a l, NumWritten        ) ;
                    U n t i l ( NumRead     =0)    o r  ( NumWritten       <>  NumRead      ) ;
                    Write     (  'C o p i e d  ', T o t a l,'   b y t e s f r o m  f i l e  ' ,p a r a m s t r( 1 ) ) ;
                    W r i t e l n ( '  t o   f i l e ' , p a r a m s t r( 2 ) ) ;
                    c l o s e( f i n) ;
                    c l o s e( f o u t) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.24          BlockWrite

    Synopsis:    Write data from memory to an untyped file

Declaration:     procedure  BlockWrite(var  f:  File;const  Buf;Count:  Int64;
                                                 var  Result:  Int64)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  LongInt;
                                                 var  Result:  LongInt)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  Cardinal;
                                                 var  Result:  Cardinal)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  Word;var  Result:  Word)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  Word;
                                                 var  Result:  Integer)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  LongInt)

    Visibility:   default

Description:     BlockWrite  writes  count  records  from  buffer  to  the  file  F.A  record  is  a  block  of  bytes
                with size specified by the Rewrite (1310   ) or Reset (1308   ) statement.  If the records couldn't
                be  written  to  disk,  a  run-time  error  is  generated.  This  behavior  can  be  controlled  by  the
                \var{\{\$i\}} switch.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Blockread (1220   ), Close (1223   ), Rewrite (1310   ), Assign (1216   )
                29.9.25          Break

    Synopsis:    Exit current loop construct.

Declaration:     procedure  Break

    Visibility:   default

Description:     Break jumps to the statement following the end of the current repetitive statement.  The
                code between the Break call and the end of the repetitive statement is skipped.  The condition
                of the repetitive statement is NOT evaluated.

                This can be used with For, var{repeat} and While statements.

                Note that while this is a procedure, Break is a reserved word and hence cannot be redefined.

       Errors:   None.

    See also:    Continue (1229   ), Exit (1241   )



                                                                                1221

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                Listing:__./refex/ex87.pp__________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 8 7;


                {   Program       t o  d e m o n s t r a t et h e  B r e a k  f u n c t i o n. }


                Var     I  :   l o n g i n t;


                 b e g i n
                    I : = 0 ;
                    While      I<10    Do
                        b e g i n
                        I n c( I) ;
                        I f  I>5   Then
                           Break    ;
                        W r i t e l n( i ) ;
                       end   ;
                    I : = 0 ;
                    Repeat
                        I n c( I) ;
                        I f  I>5   Then
                           Break    ;
                        W r i t e l n( i ) ;
                    U n t i l  I>=10;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                        I f  I>5   Then
                           Break    ;
                        W r i t e l n( i ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.26          chdir

    Synopsis:    Change current working directory.

Declaration:     procedure  chdir(const  s:  String)

    Visibility:   default

Description:     Chdir changes the working directory of the process to S.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Mkdir (1271   ), Rmdir (1310   )


                Listing:__./refex/ex7.pp___________________________________________________________________________________________*
 *___________

                Program       Example7       ;


                {   Program       t o  d e m o n s t r a t et h e  C h D i r  f u n c t i o n. }


                 b e g i n
                    { $ I- }
                    ChDir     ( ParamStr      ( 1 ) ) ;
                    i f  I O r e s u l t<>0   then
                        W r i t e l n(  'Cannot      c h a n g e t o   d i r e c t o r y:   ' ,p a r a m s t r ( 1 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________
                                                                                1222

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.27          chr

    Synopsis:    Convert byte value to character value

Declaration:     function  chr(b:  Byte)  :  Char

    Visibility:   default

Description:     Chr returns the character which has ASCII value X.

                Historical note:

                Originally,  Pascal  did  not  have  typecasts  and  chr  was  a  necessary  function  in  order  to  do
                certain operations on ASCII values of characters.  With the arrival of typecasting a generic
                approach  became  possible,  making  chr  mostly  obselete.   However,  chr  is  not  considered
                deprecated and remains in wide use today.

       Errors:   None.

    See also:    Ord (1299   ), Str (1325   )


                Listing:  ./refex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  Chr    f u n c t i o n. }


                 b e g i n
                    Write     ( c h r ( 1 0 ) ,c h r( 1 3 ) ) ;{   The    same     e f f e c t a s  W r i t e l n;  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.28          Close

    Synopsis:    Close a file

Declaration:     procedure  Close(var  f:  File)
                procedure  Close(var  t:  Text)

    Visibility:   default

Description:     Close flushes the buffer of the file F and closes F. After a call to Close, data can no longer
                be read from or written to F. To reopen a file closed with Close, it isn't necessary to assign
                the file again.  A call to Reset (1308   ) or Rewrite (1310   ) is sufficient.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Assign (1216   ), Reset (1308   ), Rewrite (1310   ), Flush (1247   )


                Listing:  ./refex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   Program       t o  d e m o n s t r a t et h e  C l o s e  f u n c t i o n. }


                Var    F   :   t e x t;


                 b e g i n
                  A s s i g n ( f , 'T e s t .t x t ') ;
                  ReWrite       ( F ) ;



                                                                                1223

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                  W r i t e l n ( F , 'Some     t e x t  w r i t t e n t o  T e s t. t x t' ) ;
                  c l o s e  ( f ) ; {   F l u s h e s c o n t e n t s o f  b u f f e r t o  d i s k,
                                         c l o s e s t h e   f i l e.  O m i t t i n gt h i s  may
                                         c a u s e d a t a  NOT    t o  be    w r i t t e n t o  d i s k.}
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.29          CompareByte

    Synopsis:    Compare 2 memory buffers byte per byte

Declaration:     function  CompareByte(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareByte compares two memory regions buf1,buf2 on a byte-per-byte basis for a total
                of  len bytes.

                The function returns one of the following values:


                less than 0      if buf1 and buf2 contain different bytes in the first len bytes, and the first such
                       byte is smaller in buf1 than the byte at the same position in buf2.

                0 if the first len bytes in buf1 and buf2 are equal.  \item [greater than 0] if  buf1 and buf2
                       contain different bytes in the first len bytes, and the first such byte is larger in buf1
                       than the byte at the same position in buf2.


       Errors:   None.

    See also:    CompareChar (1225   ), CompareWord (1228   ), CompareDWord (1227   )


                Listing:  ./refex/ex99.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 9;


                {   Program       t o  d e m o n s t r a t et h e  CompareByte          f u n c t i o n. }


                Const
                    A r r a y S i z e       =  1 0 0 ;
                    H a l f A r r a y S i z e=  A r r a y S i z eDiv    2 ;


                Var
                    Buf1   , Buf2     :  A r r a y[ 1 . .A r r a y S i z e] o f  b y t e;
                    I   :  l o n g i n t;


                    P r o c e d u r eCheckPos      ( Len    :   L o n g i n t) ;


                    Begin
                       Write    ( ' F i r s t  ', Len  , '  p o s i t i o n s a r e  ') ;
                        i f  CompareByte        ( Buf1   ,Buf2    ,Len  )<>0     then
                           Write    ( 'NOT     ') ;
                        W r i t e l n('e q u a l' ) ;
                    end  ;



                 b e g i n
                    For    I : = 1  t o  A r r a y S i z edo
                        b e g i n
                       Buf1    [i ] : =I ;
                                                                                1224

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                        I f  I<=  H a l f A r r a y S i z eThen
                           Buf2   [ I] : = I
                        e l s e
                           Buf2   [ i] : = H a l f A r r a y S i z-eI;
                       end   ;
                    CheckPos      ( H a l f A r r a y S i z ed i v 2 ) ;
                    CheckPos      ( H a l f A r r a y S i z)e;
                    CheckPos      ( H a l f A r r a y S i z+e1 ) ;
                    CheckPos      ( H a l f A r r a y S i z e+  H a l f A r r a y S i z eDiv   2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.30          CompareChar

    Synopsis:    ompare 2 memory buffers character per character

Declaration:     function  CompareChar(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareChar compares two memory regions buf1,buf2 on a character-per-character basis
                for a total of  len characters.

                The CompareChar0 variant compares len bytes, or until a zero character is found.

                The function returns one of the following values:


                -1 if  buf1 and buf2 contain different characters in the first len positions, and the first such
                       character is smaller in buf1 than the character at the same position in buf2.

                0 if the first len characters in buf1 and buf2 are equal.

                1 if  buf1 and buf2 contain different characters in the first len positions, and the first such
                       character is larger in buf1 than the character at the same position in buf2.


       Errors:   None.

    See also:    CompareByte (1224   ), CompareWord (1228   ), CompareDWord (1227   )


                Listing:  ./refex/ex100.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 0;


                {   Program       t o  d e m o n s t r a t et h e  CompareChar          f u n c t i o n. }


                Const
                    A r r a y S i z e       =  1 0 0 ;
                    H a l f A r r a y S i z e=  A r r a y S i z eDiv    2 ;


                Var
                    Buf1   , Buf2     :  A r r a y[ 1 . .A r r a y S i z e] o f  c h a r;
                    I   :  l o n g i n t;


                    P r o c e d u r eCheckPos      ( Len    :   L o n g i n t) ;


                    Begin
                       Write    ( ' F i r s t  ', Len  , '  c h a r a c t e r sa r e   ') ;
                        i f  CompareChar        ( Buf1   ,Buf2    ,Len  )<>0     then
                           Write    ( 'NOT     ') ;
                        W r i t e l n('e q u a l' ) ;
                    end  ;



                                                                                1225

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________


                    P r o c e d u r eC h e c k N u l l P o(sLen    :   L o n g i n t) ;


                    Begin
                       Write    ( ' F i r s t  ', Len  , '  non  - n u l l  c h a r a c t e r sa r e  ' ) ;
                        i f  CompareChar0         (Buf1    ,Buf2   , Len  )<>0     then
                           Write    ( 'NOT     ') ;
                        W r i t e l n('e q u a l' ) ;
                    end  ;


                 b e g i n
                    For    I : = 1  t o  A r r a y S i z edo
                        b e g i n
                       Buf1    [i ] : =c h r( I ) ;
                        I f  I<=  H a l f A r r a y S i z eThen
                           Buf2   [ I] : = c h r( I)
                        e l s e
                           Buf2   [ i] : = c h r( H a l f A r r a y S i z-eI) ;
                       end   ;
                    CheckPos      ( H a l f A r r a y S i z ed i v 2 ) ;
                    CheckPos      ( H a l f A r r a y S i z)e;
                    CheckPos      ( H a l f A r r a y S i z+e1 ) ;
                    CheckPos      ( H a l f A r r a y S i z e+  H a l f A r r a y S i z eDiv   2 ) ;
                    For    I : = 1  t o  4  do
                        b e g i n
                        b u f 1[Random     ( A r r a y S i z)e+1]:=   Chr   ( 0 ) ;
                        b u f 2[Random     ( A r r a y S i z)e+1]:=   Chr   ( 0 ) ;
                       end   ;
                    Randomize       ;
                    C h e c k N u l l P o(sH a l f A r r a y S i z ed i v 2 ) ;
                    C h e c k N u l l P o(sH a l f A r r a y S i z)e;
                    C h e c k N u l l P o(sH a l f A r r a y S i z+e1 ) ;
                    C h e c k N u l l P o(sH a l f A r r a y S i z e+  H a l f A r r a y S i z eDiv   2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.31          CompareChar0

    Synopsis:    Compare two buffers character by character till a null-character is reached.

Declaration:     function  CompareChar0(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareChar0 compares 2 buffers buf1 and buf2 for a maximum length of len or till a null
                character is reached in either buffer.  The result depends on the contents of the buffers:


                < 0 If  buf1 contains a character less than the corresponding character in buf2.

                0 If both buffers are equal

                > 0  If  buf1 contains a character greater than the corresponding character in buf2.


       Errors:   None.

    See also:    CompareByte (1224   ), CompareChar (1225   ), CompareDWord (1227   ), CompareWord (1228   )

                                                                                1226

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.32          CompareDWord

    Synopsis:    Compare 2 memory buffers DWord per DWord

Declaration:     function  CompareDWord(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareDWord compares two memory regions buf1,buf2 on a DWord-per-DWord basis for
                a total of  len DWords.  (A DWord is 4 bytes).

                The function returns one of the following values:


                -1 if  buf1  and  buf2  contain  different  DWords  in  the  first  len  DWords,  and  the  first  such
                       DWord is smaller in buf1 than the DWord at the same position in buf2.

                0 if the first len DWords in buf1 and buf2 are equal.

                1 if  buf1  and  buf2  contain  different  DWords  in  the  first  len  DWords,  and  the  first  such
                       DWord is larger in buf1 than the DWord at the same position in buf2.


       Errors:   None.

    See also:    CompareChar (1225   ), CompareByte (1224   ), CompareWord (1228   )


                Listing:  ./refex/ex101.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 1;


                {   Program       t o  d e m o n s t r a t et h e  CompareDWord           f u n c t i o n. }


                Const
                    A r r a y S i z e       =  1 0 0 ;
                    H a l f A r r a y S i z e=  A r r a y S i z eDiv    2 ;


                Var
                    Buf1   , Buf2     :  A r r a y[ 1 . .A r r a y S i z e] o f  Dword    ;
                    I   :  l o n g i n t;


                    P r o c e d u r eCheckPos      ( Len    :   L o n g i n t) ;


                    Begin
                       Write    ( ' F i r s t  ', Len  , '  DWords      a r e   ') ;
                        i f  CompareDWord         (Buf1    ,Buf2   , Len  )<>0     then
                           Write    ( 'NOT     ') ;
                        W r i t e l n('e q u a l' ) ;
                    end  ;



                 b e g i n
                    For    I : = 1  t o  A r r a y S i z edo
                        b e g i n
                       Buf1    [i ] : =I ;
                        I f  I<=  H a l f A r r a y S i z eThen
                           Buf2   [ I] : = I
                        e l s e
                           Buf2   [ i] : = H a l f A r r a y S i z-eI;
                       end   ;
                    CheckPos      ( H a l f A r r a y S i z ed i v 2 ) ;
                    CheckPos      ( H a l f A r r a y S i z)e;
                    CheckPos      ( H a l f A r r a y S i z+e1 ) ;



                                                                                1227

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    CheckPos      ( H a l f A r r a y S i z e+  H a l f A r r a y S i z eDiv   2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.33          CompareWord

    Synopsis:    Compare 2 memory buffers word per word

Declaration:     function  CompareWord(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareWord  compares  two  memory  regions  buf1,buf2  on  a  Word-per-Word  basis  for  a
                total of  len Words.  (A Word is 2 bytes).

                The function returns one of the following values:


                -1 if  buf1 and buf2 contain different Words in the first len Words, and the first such Word
                       is smaller in buf1 than the Word at the same position in buf2.

                0 if the first len Words in buf1 and buf2 are equal.

                1 if  buf1 and buf2 contain different Words in the first len Words, and the first such Word
                       is larger in buf1 than the Word at the same position in buf2.


       Errors:   None.

    See also:    CompareChar (1225   ), CompareByte (1224   ), CompareDWord (1227   )


                Listing:  ./refex/ex102.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 2;


                {   Program       t o  d e m o n s t r a t et h e  CompareWord          f u n c t i o n. }


                Const
                    A r r a y S i z e       =  1 0 0 ;
                    H a l f A r r a y S i z e=  A r r a y S i z eDiv    2 ;


                Var
                    Buf1   , Buf2     :  A r r a y[ 1 . .A r r a y S i z e] o f  Word   ;
                    I   :  l o n g i n t;


                    P r o c e d u r eCheckPos      ( Len    :   L o n g i n t) ;


                    Begin
                       Write    ( ' F i r s t  ', Len  , '  w o r d s  a r e  ' ) ;
                        i f  CompareWord        ( Buf1   ,Buf2    ,Len  )<>0     then
                           Write    ( 'NOT     ') ;
                        W r i t e l n('e q u a l' ) ;
                    end  ;



                 b e g i n
                    For    I : = 1  t o  A r r a y S i z edo
                        b e g i n
                       Buf1    [i ] : =I ;
                        I f  I<=  H a l f A r r a y S i z eThen
                           Buf2   [ I] : = I
                        e l s e



                                                                                1228

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                           Buf2   [ i] : = H a l f A r r a y S i z-eI;
                       end   ;
                    CheckPos      ( H a l f A r r a y S i z ed i v 2 ) ;
                    CheckPos      ( H a l f A r r a y S i z)e;
                    CheckPos      ( H a l f A r r a y S i z+e1 ) ;
                    CheckPos      ( H a l f A r r a y S i z e+  H a l f A r r a y S i z eDiv   2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.34          Concat

    Synopsis:    Append one string to another.

Declaration:     function  Concat(const  S1:  String;const  S2:  String;const  S3:  String;
                                         const  Sn:  String)  :  String

    Visibility:   default

Description:     Concat concatenates the strings S1,S2 etc.  to one long string.  The resulting string is trun-
                cated at a length of 255 bytes.  The same operation can be performed with the + operation.

       Errors:   None.

    See also:    Copy (1230   ), Delete (1233   ), Insert (1262   ), Pos (1301   ), Length (1267   )


                Listing:  ./refex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                {   Program       t o  d e m o n s t r a t et h e  C o n c a t f u n c t i o n.  }
                Var
                    S   :  S t r i n g;


                 b e g i n
                    S := Concat     ( 'T h i s  c a n  be   done   ' , '  E a s i e r  ', ' w i t h t h e  +   o p e r a t o r! ' )*
 * ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.35          Continue

    Synopsis:    Continue with next loop cycle.

Declaration:     procedure  Continue

    Visibility:   default

Description:     Continue  jumps  to  the  end  of  the  current  repetitive  statement.   The  code  between  the
                Continue  call  and  the  end  of  the  repetitive  statement  is  skipped.   The  condition  of  the
                repetitive statement is then checked again.

                This can be used with For, var{repeat} and While statements.

                Note  that  while  this  is  a  procedure,  Continue  is  a  reserved  word  and  hence  cannot  be
                redefined.

       Errors:   None.

    See also:    Break (1221   ), Exit (1241   )


                Listing:  ./refex/ex86.pp



                                                                                1229

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 6;


                {   Program       t o  d e m o n s t r a t et h e  C o n t i n u e f u n c t i o n. }


                Var     I  :   l o n g i n t;


                 b e g i n
                    I : = 0 ;
                    While      I<10    Do
                        b e g i n
                        I n c( I) ;
                        I f  I<5   Then
                           C o n t i n u e;
                        W r i t e l n( i ) ;
                       end   ;
                    I : = 0 ;
                    Repeat
                        I n c( I) ;
                        I f  I<5   Then
                           C o n t i n u e;
                        W r i t e l n( i ) ;
                    U n t i l  I>=10;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                        I f  I<5   Then
                           C o n t i n u e;
                        W r i t e l n( i ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.36          Copy

    Synopsis:    Copy part of a string.

Declaration:     function  Copy(S:  AStringType;Index:  Integer;Count:  Integer)  :  String
                function  Copy(A:  DynArrayType;Index:  Integer;Count:  Integer)  :  DynArray

    Visibility:   default

Description:     Copy returns a string which is a copy if the Count characters in S, starting at position Index.
                If  Count is larger than the length of the string S, the result is truncated.  If  Index is larger
                than the length of the string S, then an empty string is returned.  Index is 1-based.

                For dynamical arrays, Copy returns a new dynamical array of the same type as the original
                one, and copies Count elements from the old array, starting at position Index.

       Errors:   None.

    See also:    Delete (1233   ), Insert (1262   ), Pos (1301   )


                Listing:  ./refex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   Program       t o  d e m o n s t r a t et h e  Copy     f u n c t i o n. }


                Var    S , T   :  S t r i n g;
                                                                                1230

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________


                 b e g i n
                    T :=  '1 2 3 4 5 6 7';
                    S := Copy     (T  , 1 , 2 ) ;    {  S : = ' 1 2 '     }
                    S := Copy     (T  , 4 , 2 ) ;    {  S : = ' 4 5 '     }
                    S := Copy     (T  , 4 , 8 ) ;    {  S : = ' 4 5 6 7 ' }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.37          cos

    Synopsis:    Calculate cosine of angle

Declaration:     function  cos(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Cos returns the cosine of  X, where X is an angle,  in radians.  If the absolute value of the
                argument is larger than 2^63, then the result is undefined.

       Errors:   None.

    See also:    Arctan (1215   ), Sin (1321   )


                Listing:  ./refex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;


                {   Program       t o  d e m o n s t r a t et h e  Cos    f u n c t i o n. }


                Var    R   :   R e a l;


                 b e g i n
                    R := Cos  ( P i ) ;       {  R := -1    }
                    R := Cos  ( P i / 2 ) ;   {  R : = 0    }
                    R := Cos   ( 0 ) ;        {  R : = 1    }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.38          Cseg

    Synopsis:    Return code segment

Declaration:     function  Cseg  :  Word

    Visibility:   default

Description:     CSeg returns the Code segment register.  In Free Pascal, it returns always a zero, since Free
                Pascal is a 32 bit compiler.

       Errors:   None.

    See also:    DSeg (1235   ), Seg (1316   ), Ofs (1275   ), Ptr (1302   )


                Listing:  ./refex/ex13.pp

                                                                                1231

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;


                {   Program       t o  d e m o n s t r a t et h e  CSeg     f u n c t i o n. }


                 v a r W   :  word    ;


                 b e g i n
                   W  := CSeg    ;  {W : = 0 ,  p r o v i d e d f o r  c o m p a t i b i l i t,y
                                                FPC    i s  3 2   b i t.}
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.39          Dec

    Synopsis:    Decrease value of variable

Declaration:     procedure  Dec(var  X:  TOrdinal)
                procedure  Dec(var  X:  TOrdinal;Decrement:  TOrdinal)

    Visibility:   default

Description:     Dec decreases the value of  X with Decrement.  If  Decrement isn't specified, then 1 is taken
                as a default.

       Errors:   A range check can occur, or an underflow error, if an attempt it made to decrease X below
                its minimum value.

    See also:    Inc (1256   )


                Listing:  ./refex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                {   Program       t o  d e m o n s t r a t et h e  Dec    f u n c t i o n. }


                Var
                    I     :  I n t e g e r;
                    L     :  L o n g i n t;
                   W      :  Word   ;
                    B     :  B y t e;
                    S i  :   S h o r t I n t;


                 b e g i n
                  I : = 1 ;
                  L : = 2 ;
                 W  : = 3 ;
                  B : = 4 ;
                  S i : = 5 ;
                  Dec    ( i ) ;       {   i: = 0    }
                  Dec    ( L , 2 ) ;   {  L : = 0    }
                  Dec    (W  , 2 ) ;   {  W : = 1    }
                  Dec    ( B , - 2 ) ; {  B : = 6    }
                  Dec    ( S i , 0 ) ; {   S i: = 5  }
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1232

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.40          DefaultAnsi2WideMove

    Synopsis:    Standard implementation of Ansi to Widestring conversion routine

Declaration:     procedure  DefaultAnsi2WideMove(source:  PChar;var  dest:  widestring;
                                                                  len:  SizeInt)

    Visibility:   default

Description:     DefaultAnsi2WideMove  simply  copies  each  character  of  the  null-terminated  ansi-string
                Source to the corresponding WideChar in Dest.  At most Len characters will be copied.

       Errors:   None.

    See also:    DefaultWide2AnsiMove (1233   )
                29.9.41          DefaultWide2AnsiMove

    Synopsis:    Standard implementation of Widestring to Ansi conversion routine

Declaration:     procedure  DefaultWide2AnsiMove(source:  PWideChar;var  dest:  ansistring;
                                                                  len:  SizeInt)

    Visibility:   default

Description:     DefaultWide2AnsiMove simply copies each character from Source having an ordinal value
                of  less  than  255  to  the  corresponding  character  in  Dest.   Characters  having  an  ordinal
                valuelarger  than  255  will  be  replaced  by  question  marks.  At  most  Len  characters  will  be
                copied.

       Errors:   None.

    See also:    DefaultAnsi2WideMove (1233   )
                29.9.42          Delete

    Synopsis:    Delete part of a string.

Declaration:     procedure  Delete(var  s:  shortstring;index:  SizeInt;count:  SizeInt)
                procedure  Delete(var  S:  AnsiString;Index:  SizeInt;Size:  SizeInt)
                procedure  Delete(var  S:  WideString;Index:  SizeInt;Size:  SizeInt)

    Visibility:   default

Description:     Delete removes Count characters from string S, starting at position Index.  All characters
                after  the  delected  characters  are  shifted  Count  positions  to  the  left,  and  the  length  of  the
                string is adjusted.

       Errors:   None.

    See also:    Copy (1230   ), Pos (1301   ), Insert (1262   )


                Listing:  ./refex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   Program       t o  d e m o n s t r a t et h e  D e l e t e f u n c t i o n.  }


                Var



                                                                                1233

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    S   :  S t r i n g;


                 b e g i n
                    S :=  'T h i s  i s  n o t  e a s y  ! ';
                    D e l e t e ( S , 9 , 4 ) ; {  S : = 'T h i s  i s  e a s y  ! '  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.43          Dispose

    Synopsis:    Free dynamically allocated memory

Declaration:     procedure  Dispose(P:  Pointer)
                procedure  Dispose(P:  TypedPointer;Des:  TProcedure)

    Visibility:   default

Description:     The  first  form  Dispose  releases  the  memory  allocated  with  a  call  to  New  (1273   ).   The
                pointer P must be typed.  The released memory is returned to the heap.

                The second form of Dispose accepts as a first parameter a pointer to an object type, and as
                a second parameter the name of a destructor of this object.  The destructor will be called,
                and the memory allocated for the object will be freed.

       Errors:   An runtime error will occur if the pointer doesn't point to a location in the heap.

    See also:    New (1273   ), Getmem (1251   ), Freemem (1248   )


                Listing:  ./refex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  D i s p o s e and    New    f u n c t i o n s. }


                Type     SS   =   S t r i n g[ 2 0 ] ;


                         AnObj     =   O b j e c t
                             I  :   i n t e g e r;
                             C o n s t r u c t o rI n i t;
                             D e s t r u c t o rDone   ;
                             end  ;


                Var
                    P   :  ^ SS ;
                    T   :  ^ AnObj    ;


                 C o n s t r u c t o rA n o b j.I n i t;


                 b e g i n
                  W r i t e l n ( ' I n i t i a l i z i n gan   i n s t a n c eo f  AnObj      ! ' ) ;
                end   ;


                 D e s t r u c t o rAnObj    .Done   ;


                 b e g i n
                    W r i t e l n ( ' D e s t r o y i n gan   i n s t a n c e o f  AnObj     ! ' ) ;
                end   ;


                 b e g i n



                                                                                1234

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    New    (P  ) ;
                    P ^:=  ' H e l l o,  World     ! ' ;
                    D i s p o s e (P  ) ;
                    {  P   i s  u n d e f i n e d f r o m h e r e  on   ! }
                    New  ( T , I n i t) ;
                    T ^ .i : = 0 ;
                    D i s p o s e (T  ,Done   ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.44          DoneCriticalsection

    Synopsis:    Clean up a critical section.

Declaration:     procedure  DoneCriticalsection(var  cs:  TRTLCriticalSection)

    Visibility:   default

Description:     DoneCriticalsection cleans up the critical section CS. After a call to DoneCriticalsection,
                the critical section can no longer be used with EnterCriticalsection (1237   ) or LeaveCritical-
                section (1267   ), unless it is again initialized with InitCriticalSection (1261   )

    See also:    InitCriticalsection (1261   ), EnterCriticalsection (1237   ), LeaveCriticalsection (1267   )
                29.9.45          Dseg

    Synopsis:    Return data segment

Declaration:     function  Dseg  :  Word

    Visibility:   default

Description:     DSeg returns the data segment register.  In Free Pascal, it returns always a zero, since Free
                Pascal is a 32 bit compiler.

       Errors:   None.

    See also:    CSeg (1231   ), Seg (1316   ), Ofs (1275   ), Ptr (1302   )


                Listing:  ./refex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  DSeg     f u n c t i o n. }


                Var
                   W    :  Word   ;


                 b e g i n
                   W  := DSeg    ;  {W : = 0 ,  T h i s  f u n c t i o n i s  p r o v i d e df o r  c o m p a t i b i l i t,y
                                                FPC    i s  a  3 2   b i t  c o m i l e r.}
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1235

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.46          DumpExceptionBackTrace

    Synopsis:    Create backtrace

Declaration:     procedure  DumpExceptionBackTrace(var  f:  text)

    Visibility:   default

Description:     DumpExceptionBackTrace writes a backtrace of the current exception to the file f.  If no
                exception  is  currently  being  raised,  nothing  is  written.   As  much  frames  as  available  are
                written.  If debug info is available, then file names and line numbers will be written as well.

       Errors:   No check is done to see whether f is opened for writing.

    See also:    dump_stack (1236   )
                29.9.47          Dump__Stack

    Synopsis:    Dump stack to the given text file.

Declaration:     procedure  Dump_Stack(var  f:  text;bp:  pointer)

    Visibility:   default

Description:     Dump_Stack prints a stack dump to the file f, with base frame pointer bp

       Errors:   The file f must be opened for writing or an error will occur.

    See also:    get_caller_addr (1253   ), get_caller_frame (1253   ), get_frame (1253   )
                29.9.48          DynArraySetLength

    Synopsis:    Set the length of a dynamic array

Declaration:     procedure  DynArraySetLength(var  a:  Pointer;typeInfo:  Pointer;
                                                             dimCnt:  SizeInt;lengthVec:  PSizeInt)

    Visibility:   default

Description:     DynArraySetLength  sets  the  length  of  the  dynamical  array  a  to  the  first  dimCnt  lengths
                specified in the array lengthVec.  The dynamical array type is described in typeInfo which
                points to a record of type TDynArrayTypeInfo (1198   )

                It  should  never  be  necessary  to  call  this  function  directly,  the  standard  SetLength  (1317   )
                function should be used instead.

       Errors:   If an invalid pointer is specified, an error may occur.

    See also:    SetLength (1317   ), tdynarraytypeinfo (1198   )
                29.9.49          EndThread

    Synopsis:    End the current thread.

Declaration:     procedure  EndThread(ExitCode:  DWord)
                procedure  EndThread

    Visibility:   default

                                                                                1236

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     EndThread ends the current thread.  If ExitCode is supplied, it is returned as the exit code
                for the thread to a function waiting for the thread to terminate (WaitForThreadTerminate
                (1339   )).  If it is omitted, zero is used.

                This function does not return.

    See also:    WaitForThreadTerminate (1339   ), BeginThread (1218   )
                29.9.50          EnterCriticalsection

    Synopsis:    Enter a critical section

Declaration:     procedure  EnterCriticalsection(var  cs:  TRTLCriticalSection)

    Visibility:   default

Description:     EnterCriticalSection  will  suspend  the  current  thread  if  another  thread  has  currently
                entered  the  critical  section.   When  the  other  thread  has  left  the  critical  section  (through
                LeaveCriticalSection (1267   )), the current thread resumes execution.  The result is that only 1
                thread is executing code which is protected by a EnterCriticalsection and LeaveCriticalSection
                pair.

                The critical section must have been initialized with InitCriticalSection (1261   ) prior to a call
                to EnterCriticalsection.

                A call to EnterCriticalsection must always be matched by a call to LeaveCriticalSection
                (1267   ).  To avoid problems, it is best to include the code to be execute in a try...finally
                block, as follows:


                EnterCriticalSection(Section);
                    Try
                       //  Code  to  be  protected  goes  here.
                    Finally
                       LeaveCriticalSection(Section);
                    end;


                For performance reasons it is best to limit the code between the entering and leaving of a
                critical section as short as possible.

    See also:    InitCriticalsection (1261   ), DoneCriticalsection (1235   ), LeaveCriticalsection (1267   )
                29.9.51          EOF

    Synopsis:    Check for end of file

Declaration:     function  EOF(var  f:  File)  :  Boolean
                function  EOF(var  t:  Text)  :  Boolean
                function  EOF  :  Boolean

    Visibility:   default

Description:     Eof returns True if the file-pointer has reached the end of the file, or if the file is empty.  In
                all other cases Eof returns False.  If no file F is specified, standard input is assumed.

                Note that calling this function may cause your program to wait:  to determine whether you
                are at EOF, it is necessary to read data.  If the file descriptor is not a real file (for instance
                for  standard  input  or  sockets)  ,  then  this  call  may  seem  to  hang  the  program  while  it  is
                waiting for data to appear or for the file descriptor to be closed.



                                                                                1237

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Eoln (1238   ), Assign (1216   ), Reset (1308   ), Rewrite (1310   )


                Listing:  ./refex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  E o f  f u n c t i o n. }


                Var    T1  ,T2    :   t e x t;
                       C   :  Char    ;


                 b e g i n
                    {   S e t  f i l e t o  r e a d  f r o m.  Empty      means     f r o m  s t a n d a r d i n p u t.}
                    a s s i g n ( t1  ,p a r a m s t r( 1 ) ) ;
                    r e s e t ( t 1 ) ;
                    {   S e t  f i l e t o   w r i t e t o .  Empty     means      t o  s t a n d a r d o u t p u t. }
                    a s s i g n ( t2  ,p a r a m s t r( 2 ) ) ;
                    r e w r i t e ( t 2) ;
                    While     not    e o f (t 1 )  do
                        b e g i n
                        r e a d ( t1  ,C ) ;
                        w r i t e ( t2 , C ) ;
                       end   ;
                    C l o s e ( t 1 ) ;
                    C l o s e ( t 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.52          EOLn

    Synopsis:    Check for end of line

Declaration:     function  EOLn(var  t:  Text)  :  Boolean
                function  EOLn  :  Boolean

    Visibility:   default

Description:     Eof returns True if the file pointer has reached the end of a line, which is demarcated by a
                line-feed character (ASCII value 10), or if the end of the file is reached.  In all other cases
                Eof returns False.  If no file F is specified, standard input is assumed.  It can only be used
                on files of type Text.

       Errors:   None.

    See also:    Eof (1237   ), Assign (1216   ), Reset (1308   ), Rewrite (1310   )


                Listing:  ./refex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 9;


                {   Program       t o  d e m o n s t r a t et h e  E o l n  f u n c t i o n. }


                 b e g i n
                    {   T h i s p r o g r a m w a i t s  f o r  k e y b o a r di n p u t.  }
                    {   I t  w i l l  p r i n t True    when     an   empty      l i n e  i s  p u t  i n ,
                       and     f a l s e when     you    t y p e a   non  - empty      l i n e.



                                                                                1238

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                        I t  w i l l  o n l y s t o p  when     you    p r e s s e n t e r.}
                    While     not    E o l n  do
                        W r i t e l n( e o l n) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.53          Erase

    Synopsis:    Delete a file from disk

Declaration:     procedure  Erase(var  f:  File)
                procedure  Erase(var  t:  Text)

    Visibility:   default

Description:     Erase removes an unopened file from disk.  The file should be assigned with Assign,  but
                not opened with Reset or Rewrite

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Assign (1216   )


                Listing:  ./refex/ex20.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 0;


                {   Program       t o  d e m o n s t r a t et h e  E r a s e  f u n c t i o n. }


                Var    F   :  T e x t ;


                 b e g i n
                    {   C r e a t e a   f i l e w i t h  a  l i n e  o f  t e x t  i n  i t}
                    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  , 'Try    and    f i n d  t h i s when     I ' 'm   f i n i s h e d!  ') ;
                    c l o s e ( f ) ;
                    {  Now    r e m o v e  t h e  f i l e }
                    E r a s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.54          Error

    Synopsis:    32-bit signed integer.

Declaration:     procedure  Error(RunTimeError:  TRuntimeError)

    Visibility:   default
                29.9.55          Exclude

    Synopsis:    Exlude element from a set if it is present.

Declaration:     procedure  Exclude(var  S:  TSetType;E:  TSetElement)

    Visibility:   default
                                                                                1239

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     Exclude removes E from the set S if it is included inthe set.  E should be of the same type
                as the base type of the set S.

                Thus, the two following statements do the same thing:


                S:=S-[E];
                Exclude(S,E);


       Errors:   If  the  type  of  the  element  E  is  not  equal  to  the  base  type  of  the  set  S,  the  compiler  will
                generate an error.

    See also:    Include (1257   )


                Listing:  ./refex/ex111.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 1 1 1;


                {   Program       t o  d e m o n s t r a t et h e  I n c l u d e/E x c l u d e f u n c t i o n s}


                Type
                    TEnumA      =  ( aOne    ,aTwo   , a T h r e e) ;
                    TEnumAs      =   Set    o f  TEnumA     ;


                Var
                    SA   :  TEnumAs      ;


                    P r o c e d u r e P r i n t S e(tS   :  TEnumAs      ) ;


                    v a r
                       B   :   B o o l e a n;


                        p r o c e d u r eDoEl   (A   :  TEnumA     ;   Desc    :   S t r i n g) ;


                        b e g i n
                           I f  A   i n  S  then
                              b e g i n
                               I f B   then
                                  Write    ( ' ,' ) ;
                              B :=  True   ;
                              Write    ( Desc   ) ;
                              end   ;
                       end   ;


                    b e g i n
                       Write    ( ' [ ') ;
                       B :=  F a l s e;
                       DoEl   ( aOne   , ' aOne   ' ) ;
                       DoEl   ( aTwo   , 'aTwo    ' ) ;
                       DoEl   ( a T h r e e, 'a T h r e e' ) ;
                        W r i t e l n('] ' )
                    end  ;


                 b e g i n
                    SA  : = [ ] ;
                    I n c l u d e(SA  ,aOne   ) ;
                    P r i n t S e t(SA ) ;
                    I n c l u d e(SA  ,a T h r e e) ;
                    P r i n t S e t(SA ) ;
                    E x c l u d e(SA  ,aOne   ) ;



                                                                                1240

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    P r i n t S e t(SA ) ;
                    E x c l u d e(SA  ,aTwo   ) ;
                    P r i n t S e t(SA ) ;
                    E x c l u d e(SA  ,a T h r e e) ;
                    P r i n t S e t(SA ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.56          Exit

    Synopsis:    Exit current subroutine.

Declaration:     procedure  Exit(const  X:  TAnyType)
                procedure  Exit

    Visibility:   default

Description:     Exit  exits  the  current  subroutine,  and  returns  control  to  the  calling  routine.   If  invoked
                in  the  main  program  routine,  exit  stops  the  program.  The  optional  argument  X  allows  to
                specify  a  return  value,  in  the  case  Exit  is  invoked  in  a  function.  The  function  result  will
                then be equal to X.

       Errors:   None.

    See also:    Halt (1253   )


                Listing:  ./refex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 1;


                {   Program       t o  d e m o n s t r a t et h e  E x i t  f u n c t i o n. }


                 P r o c e d u r eDoAnExit        (Yes     :  B o o l e a n) ;


                {   T h i s  p r o c e d u r ed e m o n s t r a t e st h e  n o r m a l E x i t  }


                 b e g i n
                    W r i t e l n ( ' H e l l o f r o m  DoAnExit       ! ' ) ;
                    I f  Yes    then
                        b e g i n
                        W r i t e l n(  'B a i l i n g o u t  e a r l y. ') ;
                        e x i t;
                       end   ;
                    W r i t e l n ( ' C o n t i n u i n gt o  t h e  end  . ' ) ;
                end   ;


                 F u n c t i o nP o s i t i v e ( Which     :   I n t e g e r)  :  B o o l e a n;


                {   T h i s  f u n c t i o n d e m o n s t r a t e st h e e x t r a FPC     f e a t u r e o f  E x i t :
                    You    c a n  s p e c i f y a   r e t u r n v a l u e f o r  t h e  f u n c t i o n }


                 b e g i n
                    i f  Which    >0   then
                        e x i t ( True   )
                    e l s e
                        e x i t ( F a l s e) ;
                end   ;


                 b e g i n



                                                                                1241

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    {   T h i s  c a l l w i l l  go   t o  t h e  end    }
                    DoAnExit        ( F a l s e) ;
                    {   T h i s  c a l l w i l l  b a i l o u t   e a r l y }
                    DoAnExit        (True    ) ;
                    i f  P o s i t i v e ( - 1 )  then
                        W r i t e l n(  'The    c o m p i l e r i s  n u t s,  - 1   i s  n o t  p o s i t i v e.')
                    e l s e
                        W r i t e l n(  'The    c o m p i l e r i s  n o t  s o  bad  ,  - 1   s e e m s t o   be   n e g a t i v e*
 *.' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.57          exp

    Synopsis:    Exponentiate

Declaration:     function  exp(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Exp returns the exponent of  X, i.e.  the number e to the power X.

       Errors:   None.

    See also:    Ln (1268   ), Power (1165   )


                Listing:  ./refex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   Program       t o  d e m o n s t r a t et h e  Exp    f u n c t i o n. }


                 b e g i n
                    W r i t e l n ( Exp  ( 1 ) : 8 : 2 ) ;{   S h o u l d p r i n t 2 . 7 2  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.58          FilePos

    Synopsis:    Get position in file

Declaration:     function  FilePos(var  f:  File)  :  Int64

    Visibility:   default

Description:     Filepos returns the current record position of the file-pointer in file F. It cannot be invoked
                with a file of type Text.  A compiler error will be generated if this is attempted.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Filesize (1243   )


                Listing:  ./refex/ex23.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 3;


                {   Program       t o  d e m o n s t r a t et h e  F i l e P o s f u n c t i o n. }


                Var    F   :   F i l e o f   L o n g i n t;



                                                                                1242

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                       L , FP   :   l o n g i n t;


                 b e g i n
                    {   F i l l a   f i l e w i t h  d a t a  :
                       Each     p o s i t i o n c o n t a i n s t h e  p o s i t i o n!   }
                    A s s i g n ( F , 't e s t. tmp  ' ) ;
                    R e w r i t e (F  ) ;
                    For    L : = 0  t o  1 0 0  do
                        b e g i n
                       FP  :=  F i l e P o s(F) ;
                       Write      (F  ,FP  ) ;
                       end   ;
                    C l o s e ( F ) ;
                    R e s e t ( F ) ;
                    {   I f  a l l  g o e s  w e l l,  n o t h i n g i s  d i s p l a y e d h e r e.  }
                    While     not    ( Eof  ( F ) )  do
                        b e g i n
                       FP  :=  F i l e P o s( F ) ;
                       Read     ( F ,L ) ;
                        i f  L<>  FP   then
                           W r i t e l n ( 'S o m e t h i n g wrong    :  Got    ' , l, '  on    p o s  ' ,FP  ) ;
                       end   ;
                    C l o s e ( F ) ;
                    E r a s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.59          FileSize

    Synopsis:    Size of file

Declaration:     function  FileSize(var  f:  File)  :  Int64

    Visibility:   default

Description:     Filesize returns the total number of records in file F. It cannot be invoked with a file of
                type Text.  (under linux and unix, this also means that it cannot be invoked on pipes).  If  F
                is empty, 0 is returned.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Filepos (1242   )


                Listing:  ./refex/ex24.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 4;


                {   Program       t o  d e m o n s t r a t et h e  F i l e S i z e f u n c t i o n. }


                Var    F   :   F i l e Of   b y t e ;
                       L   :   F i l e Of    L o n g i n t;


                 b e g i n
                    A s s i g n ( F ,p a r a m s t r( 1 ) ) ;
                    R e s e t ( F ) ;
                    W r i t e l n ( ' F i l e s i z e  i n  b y t e s  :  ' , F i l e S i z(eF ) ) ;
                    C l o s e ( F ) ;
                    A s s i g n ( L ,p a r a m s t r ( 1 ) ) ;



                                                                                1243

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    R e s e t ( L ) ;
                    W r i t e l n ( ' F i l e s i z e  i n  L o n g i n t s :   ', F i l e S i z e(L) ) ;
                    C l o s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.60          FillByte

    Synopsis:    Fill memory region with 8-bit pattern

Declaration:     procedure  FillByte(var  x;count:  SizeInt;value:  Byte)

    Visibility:   default

Description:     FillByte fills the memory starting at X with Count bytes with value equal to Value.  This
                is useful for quickly zeroing out a memory location.  When the size of the memory location
                to  be  filled  out  is  a  multiple  of  2  bytes,  it  is  better  to  use  Fillword  (1246   ),  and  if  it  is*
 *  a
                multiple  of  4  bytes  it  is  better  to  use  FillDWord  (1245   ),  these  routines  are  optimized  for
                their respective sizes.

       Errors:   No checking on the size of  X is done.

    See also:    Fillchar (1245   ), FillDWord (1245   ), Fillword (1246   ), Move (1272   )


                Listing:  ./refex/ex102.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 2;


                {   Program       t o  d e m o n s t r a t et h e  CompareWord          f u n c t i o n. }


                Const
                    A r r a y S i z e       =  1 0 0 ;
                    H a l f A r r a y S i z e=  A r r a y S i z eDiv    2 ;


                Var
                    Buf1   , Buf2     :  A r r a y[ 1 . .A r r a y S i z e] o f  Word   ;
                    I   :  l o n g i n t;


                    P r o c e d u r eCheckPos      ( Len    :   L o n g i n t) ;


                    Begin
                       Write    ( ' F i r s t  ', Len  , '  w o r d s  a r e  ' ) ;
                        i f  CompareWord        ( Buf1   ,Buf2    ,Len  )<>0     then
                           Write    ( 'NOT     ') ;
                        W r i t e l n('e q u a l' ) ;
                    end  ;



                 b e g i n
                    For    I : = 1  t o  A r r a y S i z edo
                        b e g i n
                       Buf1    [i ] : =I ;
                        I f  I<=  H a l f A r r a y S i z eThen
                           Buf2   [ I] : = I
                        e l s e
                           Buf2   [ i] : = H a l f A r r a y S i z-eI;
                       end   ;
                    CheckPos      ( H a l f A r r a y S i z ed i v 2 ) ;
                    CheckPos      ( H a l f A r r a y S i z)e;



                                                                                1244

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    CheckPos      ( H a l f A r r a y S i z+e1 ) ;
                    CheckPos      ( H a l f A r r a y S i z e+  H a l f A r r a y S i z eDiv   2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.61          FillChar

    Synopsis:    Fill memory region with certain character

Declaration:     procedure  FillChar(var  x;count:  SizeInt;Value:  Byte)
                procedure  FillChar(var  x;count:  SizeInt;Value:  Boolean)
                procedure  FillChar(var  x;count:  SizeInt;Value:  Char)

    Visibility:   default

Description:     Fillchar fills the memory starting at X with Count bytes or characters with value equal to
                Value.

       Errors:   No checking on the size of  X is done.

    See also:    Fillword (1246   ), Move (1272   ), FillByte (1244   ), FillDWord (1245   )


                Listing:  ./refex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   Program       t o  d e m o n s t r a t et h e  F i l l C h a r f u n c t i o n. }


                Var    S   :   S t r i n g[ 1 0 ] ;
                        I  :  B y t e ;
                 b e g i n
                    For    i : = 1 0 downto       0  do
                        b e g i n
                       {   F i l l S   w i t h  i   s p a c e s}
                        F i l l C h a r( S ,S i z e O f(S ) , '   ') ;
                       {   S e t  L e n g t h }
                        S e t L e n g t(hS , I) ;
                        W r i t e l n( s , '*  ') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.62          FillDWord

    Synopsis:    Fill memory region with 32-bit pattern

Declaration:     procedure  FillDWord(var  x;count:  SizeInt;value:  DWord)

    Visibility:   default

Description:     Fillword fills the memory starting at X with Count DWords with value equal to Value.  A
                DWord is 4 bytes in size.

       Errors:   No checking on the size of  X is done.

    See also:    FillByte (1244   ), Fillchar (1245   ), Fillword (1246   ), Move (1272   )


                Listing:  ./refex/ex103.pp
                                                                                1245

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 3;


                {   Program       t o  d e m o n s t r a t et h e  F i l l B y t e f u n c t i o n. }


                Var    S   :   S t r i n g[ 1 0 ] ;
                        I  :  B y t e ;


                 b e g i n
                    For    i : = 1 0 downto       0  do
                        b e g i n
                       {   F i l l S   w i t h  i   b y t e s }
                        F i l l C h a r( S ,S i z e O f(S  ) , 3 2 ) ;
                       {   S e t  L e n g t h }
                        S e t L e n g t(hS , I) ;
                        W r i t e l n( s , '*  ') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.63          FillWord

    Synopsis:    Fill memory region with 16-bit pattern

Declaration:     procedure  FillWord(var  x;count:  SizeInt;Value:  Word)

    Visibility:   default

Description:     Fillword fills the memory starting at X with Count words with value equal to Value.  A
                word is 2 bytes in size.

       Errors:   No checking on the size of  X is done.

    See also:    Fillchar (1245   ), Move (1272   )


                Listing:  ./refex/ex76.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 6;


                {   Program       t o  d e m o n s t r a t et h e  F i l l W o r d f u n c t i o n. }


                Var    W   :  A r r a y[ 1 . . 1 0 0 ] o f  Word   ;


                 b e g i n
                    {  Q u i c k  i n i t i a l i z a t i o no f a r r a y W   }
                    F i l l W o r d(W , 1 0 0 , 0 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.64          FindResource

    Synopsis:    Locate a resource and return a handle to it.

Declaration:     function  FindResource(ModuleHandle:  HMODULE;ResourceName:  PChar;
                                                   ResourceType:  PChar)  :  TResourceHandle
                function  FindResource(ModuleHandle:  HMODULE;ResourceName:  AnsiString;
                                                   ResourceType:  AnsiString)  :  TResourceHandle

    Visibility:   default



                                                                                1246

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     FindResource searches for a resource with name ResourceName and of type ResourceType
                in  the  executable  or  library  identified  by  ModuleHandle.   It  returns  a  TResourceHandle
                which can be used to load the resource with LoadResource (1269   ).

       Errors:   None.  In case the resource was not found, 0 is returned.

    See also:    FreeResource  (1249   ),  LoadResource  (1269   ),  SizeofResource  (1322   ),  LockResource  (1269   ),
                UnlockResource (1335   ), FreeResource (1249   )
                29.9.65          float__raise

    Synopsis:    Raise floating point exception

Declaration:     procedure  float_raise(i:  ShortInt)

    Visibility:   default

Description:     float_raise raises the floating point exceptions specified by softfloat_exception_flags (1210   ).

    See also:    softfloat_exception_flags (1210   ), softfloat_exception_mask (1211   )
                29.9.66          Flush

    Synopsis:    Write file buffers to disk

Declaration:     procedure  Flush(var  t:  Text)

    Visibility:   default

Description:     Flush empties the internal buffer of an opened file F and writes the contents to disk.  The
                file is \textit{not} closed as a result of this call.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Close (1223   )


                Listing:  ./refex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   Program       t o  d e m o n s t r a t et h e  F l u s h  f u n c t i o n. }


                Var    F   :  T e x t ;


                 b e g i n
                    {   A s s i g nF   t o   s t a n d a r do u t p u t }
                    A s s i g n ( F , ' ') ;
                    R e w r i t e (F  ) ;
                    W r i t e l n (F  , 'T h i s  l i n e  i s  w r i t t e n f i r s t,  b u t  a p p e a r s l a t e r ! ' ) ;
                    {  At    t h i s  p o i n t t h e  t e x t  i s  i n  t h e  i n t e r n a l p a s c a l b u f f e r,
                       and    n o t   y e t  w r i t t e nt o   s t a n d a r do u t p u t }
                    W r i t e l n ( ' T h i s l i n e  a p p e a r s f i r s t,  b u t  i s  w r i t t e n l a t e r  ! ') ;
                    {  A   w r i t e l n t o  ' o u t p u t'  a l w a y s c a u s e s a   f l u s h -   s o  t h i s  t e x t  i s
                        w r i t t e nt o   s c r e e n }
                    F l u s h ( f ) ;
                    {  At    t h i s  p o i n t,  t h e  t e x t  w r i t t e nt o  F   i s  w r i t t e n t o   s c r e e n. }
                    Write     ( F , ' F i n i s h i n g' ) ;
                    C l o s e ( f ) ;    {   C l o s i n ga   f i l e  a l w a y s c a u s e s a   f l u s h f i r s t }



                                                                                1247

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    W r i t e l n ( ' o f f. ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.67          FlushThread

    Synopsis:    Flush all standard files

Declaration:     procedure  FlushThread

    Visibility:   default

Description:     FlushThread flushes any buffers from standard file descriptors such as standard input/out-
                put/error.  It  should  normally  not  be  called  by  user  code,  but  is  executed  when  a  thread
                exits.

    See also:    EndThread (1236   )
                29.9.68          frac

    Synopsis:    Return fractional part of floating point value.

Declaration:     function  frac(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Frac returns the non-integer part of  X.

       Errors:   None.

    See also:    Round (1311   ), Int (1262   )


                Listing:  ./refex/ex27.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 7;


                {   Program       t o  d e m o n s t r a t et h e  F r a c  f u n c t i o n. }


                Var    R   :   R e a l;


                 b e g i n
                    W r i t e l n ( F r a c ( 1 2 3 . 4 5 6 ) : 0 : 3 ) ; {   P r i n t s  O . 4 5 6  }
                    W r i t e l n ( F r a c ( - 1 2 3 . 4 5 6 ) : 0 : 3 ) ;{  P r i n t s- O . 4 5 6  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.69          Freemem

    Synopsis:    Release allocated memory

Declaration:     procedure  Freemem(p:  pointer;Size:  PtrInt)
                function  Freemem(p:  pointer)  :  PtrInt

    Visibility:   default

Description:     Freemem releases the memory occupied by the pointer P, of size Count (in bytes), and returns
                it to the heap.  P should point to the memory allocated to a dynamic variable.

       Errors:   An error will occur when P doesn't point to the heap.



                                                                                1248

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    See also:    Getmem (1251   ), New (1273   ), Dispose (1234   )


                Listing:__./refex/ex28.pp__________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 8;


                {   Program       t o  d e m o n s t r a t et h e  FreeMem       and    GetMem      f u n c t i o n s. }


                Var    P   :   P o i n t e r;
                       MM    :  L o n g i n t;


                 b e g i n
                    {  Get    memory       f o r P   }
                    GetMem      ( P , 8 0 ) ;
                    F i l l C h a r (P ^ , 8 0 ,'   ') ;
                    FreeMem       (P  , 8 0 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.70          Freememory

    Synopsis:    Alias for FreeMem (1248   )

Declaration:     procedure  Freememory(p:  pointer;Size:  PtrInt)
                function  Freememory(p:  pointer)  :  PtrInt

    Visibility:   default

Description:     FreeMemory is an alias for FreeMem (1248   ).

    See also:    FreeMem (1248   )
                29.9.71          FreeResource

    Synopsis:    Free a loaded resource

Declaration:     function  FreeResource(ResData:  HGLOBAL)  :  LongBool

    Visibility:   default

Description:     FreeResource unloads the resource identified by ResData from memory.  The resource must
                have been loaded by LoadResource (1269   ).  It returns True if the operation was succesful,
                False otherwise.

       Errors:   On error, False is returned.

    See also:    FindResource  (1246   ),  LoadResource  (1269   ),  SizeofResource  (1322   ),  LockResource  (1269   ),
                UnlockResource (1335   ), FreeResource (1249   )
                29.9.72          GetCurrentThreadId

    Synopsis:    Return the id of the currently running thread.

Declaration:     function  GetCurrentThreadId  :  TThreadID

    Visibility:   default

Description:     GetCurrentThreadId returns the ID of the currently running thread.  It can be used in calls
                such as KillThread (1266   ) or ThreadSetPriority (1333   )



                                                                                1249

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
       Errors:   None.

    See also:    KillThread (1266   ), ThreadSetPriority (1333   )
                29.9.73          getdir

    Synopsis:    Return the current directory

Declaration:     procedure  getdir(drivenr:  Byte;var  dir:  shortstring)
                procedure  getdir(drivenr:  Byte;var  dir:  ansistring)

    Visibility:   default

Description:     Getdir returns in dir the current directory on the drive drivenr, where {drivenr} is 1 for
                the first floppy drive, 3 for the first hard disk etc.  A value of 0 returns the directory on the
                current disk.  On linux and unix systems, drivenr is ignored, as there is only one directory
                tree.

       Errors:   An error is returned under dos, if the drive requested isn't ready.

    See also:    Chdir (1222   )


                Listing:  ./refex/ex29.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 9;


                {   Program       t o  d e m o n s t r a t et h e  G e t D i r f u n c t i o n.  }


                Var    S   :   S t r i n g;


                 b e g i n
                    G e t D i r ( 0 ,S ) ;
                    W r i t e l n ( ' C u r r e n t d i r e c t o r yi s  :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.74          GetFPCHeapStatus

    Synopsis:    Return FPC heap manager status information

Declaration:     function  GetFPCHeapStatus  :  TFPCHeapStatus

    Visibility:   default

Description:     Return FPC heap manager status information

       Errors:
                29.9.75          GetHeapStatus

    Synopsis:    Return the memory manager heap status.

Declaration:     function  GetHeapStatus  :  THeapStatus

    Visibility:   default
                                                                                1250

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.76          GetMem

    Synopsis:    Allocate new memory on the heap

Declaration:     procedure  Getmem(var  p:  pointer;Size:  PtrInt)
                function  GetMem(size:  PtrInt)  :  pointer

    Visibility:   default

Description:     Getmem reserves Size bytes memory on the heap, and returns a pointer to this memory in
                p.  If no more memory is available, nil is returned.

                For an example, see Freemem (1248   ).

       Errors:   None.

    See also:    Freemem (1248   ), Dispose (1234   ), New (1273   )
                29.9.77          GetMemory

    Synopsis:    Alias for GetMem (1251   )

Declaration:     procedure  Getmemory(var  p:  pointer;Size:  PtrInt)
                function  GetMemory(size:  PtrInt)  :  pointer

    Visibility:   default

Description:     Getmemory is an alias for GetMem (1251   ).

    See also:    GetMem (1251   )
                29.9.78          GetMemoryManager

    Synopsis:    Return current memory manager

Declaration:     procedure  GetMemoryManager(var  MemMgr:  TMemoryManager)

    Visibility:   default

Description:     GetMemoryManager stores the current Memory Manager record in MemMgr.

                For an example, see \progref.

       Errors:   None.

    See also:    SetMemoryManager (1318   ), IsMemoryManagerSet (1266   )
                29.9.79          GetProcessID

    Synopsis:    Get the current process ID

Declaration:     function  GetProcessID  :  SizeUInt

    Visibility:   default

Description:     GetProcessID returns the current process ID. The meaning of the return value of this call
                is system dependent.

       Errors:   None.

    See also:    GetThreadID (1252   )



                                                                                1251

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.80          GetThreadID

    Synopsis:    Get the current Thread ID.

Declaration:     function  GetThreadID  :  TThreadID

    Visibility:   default

Description:     GetThreadID returns the current process ID. The meaning of the return value of this call
                is system dependent.

    See also:    GetProcessID (1251   )
                29.9.81          GetThreadManager

    Synopsis:    Return the current thread manager

Declaration:     function  GetThreadManager(var  TM:  TThreadManager)  :  Boolean

    Visibility:   default

Description:     GetThreadManager returns the currently used thread manager in TM.

                For more information about thread programming, see the programmer's guide.

    See also:    SetThreadManager (1320   ), TThreadManager (1205   )
                29.9.82          GetVariantManager

    Synopsis:    Return the current variant manager.

Declaration:     procedure  GetVariantManager(var  VarMgr:  tvariantmanager)

    Visibility:   default

Description:     GetVariantManager returns the current variant manager in varmgr.

    See also:    IsVariantManagerSet (1165   ), SetVariantManager (1320   )
                29.9.83          GetWideStringManager

    Synopsis:    Return a copy of the currently active widestring manager.

Declaration:     procedure  GetWideStringManager(var  Manager:  TWideStringManager)

    Visibility:   default

Description:     GetWideStringManager returns a copy of the currently active heap manager in Old

                WideStrings are implemented in different ways on different platforms.  Therefore, the Free
                Pascal Runtime library has no fixed implementation of widestring routines.  Instead, it defines
                a WideString manager record,  with callbacks that can be set to an implementation which
                is most efficient on the current platform.  On windows, standard Windows routines will be
                used.  On Unix and Linux,  an implementation based on the C library is available (in unit
                cwstrings).

                It is possible to implement a custom widestring manager, optimized for the current applica-
                tion, without having to recompile the complete Run-Time Library.

    See also:    SetWideStringManager (1320   ), TWideStringManager (1208   )
                                                                                1252

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.84          get__caller__addr

    Synopsis:    Return the address of the caller.

Declaration:     function  get_caller_addr(framebp:  pointer)  :  pointer

    Visibility:   default

Description:     get_caller_frame  returns  a  pointer  to  address  (  the  return  address)  of  the  caller  of  the
                routine which has as frame framebp.

    See also:    get_frame (1253   ), get_caller_frame (1253   ), Dump_Stack (1236   )
                29.9.85          get__caller__frame

    Synopsis:    Return the frame pointer of the caller

Declaration:     function  get_caller_frame(framebp:  pointer)  :  pointer

    Visibility:   default

Description:     get_caller_frame returns a pointer to the frame of the caller of the routine which has as
                frame framebp.

    See also:    get_caller_addr (1253   ), get_frame (1253   ), Dump_Stack (1236   )
                29.9.86          get__frame

    Synopsis:    Return the current frame

Declaration:     function  get_frame  :  pointer

    Visibility:   default

Description:     get_frame returns a pointer to the current stack frame.

    See also:    get_caller_addr (1253   ), get_caller_frame (1253   )
                29.9.87          halt

    Synopsis:    Stop program execution.

Declaration:     procedure  halt(errnum:  Byte)
                procedure  halt

    Visibility:   default

Description:     Halt  stops  program  execution  and  returns  control  to  the  calling  program.   The  optional
                argument Errnum specifies an exit value.  If omitted, zero is returned.

       Errors:   None.

    See also:    Exit (1241   )


                Listing:  ./refex/ex30.pp

                                                                                1253

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 0;


                {   Program       t o  d e m o n s t r a t et h e  H a l t  f u n c t i o n. }


                 b e g i n
                  W r i t e l n ( ' B e f o r e H a l t. ' ) ;
                  H a l t  ( 1 ) ;  {  S t o p  w i t h  e x i t c o d e  1  }
                  W r i t e l n ( ' A f t e r H a l t  d o e s n' 't   g e t  e x e c u t e d.') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.88          hexStr

    Synopsis:    Convert integer value to string with hexadecimal representation.

Declaration:     function  hexStr(Val:  LongInt;cnt:  Byte)  :  shortstring
                function  hexStr(Val:  Int64;cnt:  Byte)  :  shortstring
                function  hexStr(Val:  qword;cnt:  Byte)  :  shortstring
                function  hexStr(Val:  Pointer)  :  shortstring

    Visibility:   default

Description:     HexStr  returns  a  string  with  the  hexadecimal  representation  of  Value.   The  string  has
                exactly cnt charaters.  (i.e.  only the cnt rightmost nibbles are taken into account) To have
                a complete representation of a Longint-type value, 8 nibbles are needed, i.e.  cnt=8.

       Errors:   None.

    See also:    Str (1325   ), Val (1337   ), BinStr (1219   )


                Listing:  ./refex/ex81.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 8 1;


                {   Program       t o  d e m o n s t r a t et h e  H e x S t r f u n c t i o n }


                Const      V a l u e =  4 5 6 7 8 ;


                Var     I  :   l o n g i n t;


                 b e g i n
                    For    I : = 1  t o  1 0  do
                        W r i t e l n( H e x S t r(V a l u e, I ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.89          hi

    Synopsis:    Return high byte/word of value.

Declaration:     function  hi(b:  Byte)  :  Byte
                function  hi(i:  Integer)  :  Byte
                function  hi(w:  Word)  :  Byte
                function  hi(l:  LongInt)  :  Word
                function  hi(l:  DWord)  :  Word
                function  hi(i:  Int64)  :  DWord
                function  hi(q:  QWord)  :  DWord



                                                                                1254

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     Hi returns the high byte or word from X, depending on the size of X. If the size of X is 4,
                then the high word is returned.  If the size is 2 then the high byte is returned.  Hi cannot be
                invoked on types of size 1, such as byte or char.

       Errors:   None

    See also:    Lo (1268   )


                Listing:  ./refex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  Hi   f u n c t i o n.  }


                 v a r
                    L   :  L o n g i n t;
                   W    :  Word   ;


                 b e g i n
                    L : = 1  S h l  1 6 ;         {  =   $10000      }
                   W  : = 1  S h l  8 ;           {  =   $100    }
                    W r i t e l n ( Hi ( L ) ) ;  {  P r i n t s 1   }
                    W r i t e l n ( Hi (W  ) ) ;  {  P r i n t s 1   }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.90          High

    Synopsis:    Return highest index of open array or enumerated

Declaration:     function  High(Arg:  TypeOrVariable)  :  TOrdinal

    Visibility:   default

Description:     The return value of  High depends on it's argument:


                     1.If the argument is an ordinal type, High returns the highest value in the range of the
                       given ordinal type.

                     2.If the argument is an array type or an array type variable then High returns the highest
                       possible value of it's index.

                     3.If the argument is an open array identifier in a function or procedure, then High returns
                       the highest index of the array, as if the array has a zero-based index.

                     4.If the argument is a set type then it returns the highest value of the underlying ordinal
                       type.


                The return type is always the same type as the type of the argument (This can lead to some
                nasty surprises !).

       Errors:   None.

    See also:    Low (1270   ), Ord (1299   ), Pred (1302   ), Succ (1327   )


                Listing:  ./refex/ex80.pp


                                                                                1255

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 8 0;


                {   Example       t o  d e m o n s t r a t et h e  H i g h  and    Low    f u n c t i o n s. }


                Type     TEnum     =  (    North    ,  E a s t,  South    ,  West     ) ;
                         TRange      =  1 4 . . 5 5 ;
                         T A r r a y =   A r r a y  [ 2 . . 1 0 ]o f   L o n g i n t;


                 F u n c t i o nA v e r a g e ( Row    :  A r r a y  o f  L o n g i n t)  :  R e a l;


                Var     I  :   l o n g i n t;
                       Temp     :   R e a l;



                 b e g i n
                    Temp    : =   Row   [ 0 ] ;
                    For    I  : =  1   t o  High   ( Row   )  do
                         Temp     : =  Temp    +   Row   [ i] ;
                    A v e r a g e : =  Temp     /  ( High   ( Row  ) + 1 ) ;
                end   ;


                Var    A   :  TEnum    ;
                       B   :  TRange     ;
                       C   :  T A r r a y;
                        I  :   l o n g i n t;


                 b e g i n
                    W r i t e l n ( 'TEnum        g o e s f r o m  :   ' ,Ord  ( Low  ( TEnum    ) ) ,'  t o   ' ,  Ord  ( h i g h(*
 *TEnum    ) ) , '. ' ) ;
                    W r i t e l n ( 'A            g o e s f r o m  :   ' ,Ord  ( Low  ( A ) ) ,'  t o   ' ,  Ord  ( h i g h(A ) ) ,*
 * '. ' ) ;
                    W r i t e l n ( 'TRange       g o e s f r o m  :   ' ,Ord  ( Low  ( TRange     ) ) ,'  t o   ' , Ord   ( h i g *
 *h(TRange     ) ) ,' . ') ;
                    W r i t e l n ( 'B            g o e s f r o m  :   ' ,Ord  ( Low  ( B ) ) ,'  t o   ' ,  Ord  ( h i g h(B ) ) ,*
 * '. ' ) ;
                    W r i t e l n ( 'T A r r a y  i n d e x g o e s  f r o m  :  ' ,Ord   (Low   (T A r r a y) ) ,'   t o  ' ,  Ord*
 *  ( h i g h( T A r r a y) ) ,'. ' ) ;
                    W r i t e l n ( 'C   i n d e x          g o e s  f r o m  :  ' ,Low   (C ) , '  t o   ' ,  h i g h(C ) , ' .' )*
 * ;
                    For    I := Low  ( C )  t o   High   (C )  do
                       C [ i ] : =I ;
                    W r i t e l n ( 'A v e r a g e : ' , A v e r a g e(c ) ) ;
                    Write     (  'Type     o f  r e t u r n v a l u e  i s  a l w a y s same     a s  t y p e  o f  a r g u m e n t*
 *:' ) ;
                    W r i t e l n(h i g h( h i g h(word    ) ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.91          HINSTANCE

    Synopsis:    Windows compatibility type for use in resources

Declaration:     function  HINSTANCE  :  HMODULE

    Visibility:   default

Description:     This is an opaque type.
                29.9.92          Inc

    Synopsis:    Increase value of integer variable

Declaration:     procedure  Inc(var  X:  TOrdinal)
                procedure  Inc(var  X:  TOrdinal;Increment:  TOrdinal)



                                                                                1256

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     Inc increases the value of  X with Increment.  If  Increment isn't specified, then 1 is taken
                as a default.

       Errors:   If range checking is on, then A range check can occur, or an overflow error, when an attempt
                is made to increase X over its maximum value.

    See also:    Dec (1232   )


                Listing:  ./refex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 2;


                {   Program       t o  d e m o n s t r a t et h e  I n c  f u n c t i o n. }


                Const
                    C   :  C a r d i n a l  =  1 ;
                    L   :  L o n g i n t    =  1 ;
                    I   :  I n t e g e r    =  1 ;
                   W    :  Word             =  1 ;
                    B   :  B y t e          =  1 ;
                    S I  :   S h o r t I n t=  1 ;
                    CH   :   Char           =   'A  ';


                 b e g i n
                    I n c  (C  ) ;         {  C : = 2       }
                    I n c  ( L , 5 ) ;     {  L : = 6       }
                    I n c  ( I , - 3 ) ;   {  I := -2       }
                    I n c  (W  , 3 ) ;     { W  : = 4       }
                    I n c  (B  , 1 0 0 ) ; {  B : = 1 0 1   }
                    I n c  ( S I, - 3 ) ;  {  S i := -2     }
                    I n c  (CH   , 1 ) ;   {  ch  : = 'B '  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.93          Include

    Synopsis:    Include element in set if it was not yet present.

Declaration:     procedure  Include(var  S:  TSetType;E:  TSetElement)

    Visibility:   default

Description:     Include includes E in the set S if it is not yet part of the set.  E should be of the same type
                as the base type of the set S.

                Thus, the two following statements do the same thing:


                S:=S+[E];
                Include(S,E);


                For an example, see Exclude (1239   )

       Errors:   If  the  type  of  the  element  E  is  not  equal  to  the  base  type  of  the  set  S,  the  compiler  will
                generate an error.

    See also:    Exclude (1239   )
                                                                                1257

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.94          IndexByte

    Synopsis:    Search for a byte in a memory range.

Declaration:     function  IndexByte(const  buf;len:  SizeInt;b:  Byte)  :  SizeInt

    Visibility:   default

Description:     IndexByte  searches  the  memory  at  buf  for  maximally  len  positions  for  the  byte  b  and
                returns it's position if it found one.  If  b is not found then -1 is returned.  The position is
                zero-based.

       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexChar (1258   ), IndexDWord (1259   ), IndexWord (1260   ), CompareByte (1224   )


                Listing:  ./refex/ex105.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 5;


                {   Program       t o  d e m o n s t r a t et h e  I n d e x B y t e f u n c t i o n. }


                Const
                    A r r a y S i z e=  2 5 6 ;
                    MaxValue       =  2 5 6 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f  B y t e;
                    I ,J   :   l o n g i n t;
                    K   :  B y t e;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : =Random     ( MaxValue      ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K := Random     ( MaxValue      ) ;
                       J :=  I n d e x B y t(eB u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.95          IndexChar

    Synopsis:    Search for a character in a memory range.

Declaration:     function  IndexChar(const  buf;len:  SizeInt;b:  Char)  :  SizeInt

    Visibility:   default

Description:     IndexChar searches the memory at buf for maximally len positions for the character b and
                returns it's position if it found one.  If  b is not found then -1 is returned.  The position is
                zero-based.  The IndexChar0 variant stops looking if a null character is found, and returns
                -1 in that case.
                                                                                1258

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexByte (1258   ), IndexDWord (1259   ), IndexWord (1260   ), CompareChar (1225   )


                Listing:  ./refex/ex108.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 8;


                {   Program       t o  d e m o n s t r a t et h e  I n d e x C h a r f u n c t i o n. }


                Const
                    A r r a y S i z e=  1 0 0 0 ;
                    MaxValue       =  2 6 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f  Char   ;
                    I ,J   :   l o n g i n t;
                    K   :  Char   ;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : = c h r(Ord   ( 'A ' )+ Random     (MaxValue       ) ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K :=  c h r( Ord  ( 'A  ')+ Random     ( MaxValue      ) ) ;
                       J :=  I n d e x C h a(rB u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.96          IndexChar0

    Synopsis:    Return index of a character in null-terminated array of char.

Declaration:     function  IndexChar0(const  buf;len:  SizeInt;b:  Char)  :  SizeInt

    Visibility:   default

Description:     IndexChar0 returns the index of the character b in the null-terminated array Buf.  At most
                len characters will be searched, or the null character if it is encountered first.  If the character
                is not found, 0 is returned.

       Errors:   On error, 0 is returned.

    See also:    IndexByte (1258   ), IndexChar (1258   ), IndexWord (1260   ), IndexDWord (1259   ), CompareChar0
                (1226   )
                29.9.97          IndexDWord

    Synopsis:    Search for a DWord value in a memory range.

Declaration:     function  IndexDWord(const  buf;len:  SizeInt;b:  DWord)  :  SizeInt

    Visibility:   default



                                                                                1259

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     IndexChar searches the memory at buf for maximally len positions for the DWord DW and
                returns it's position if it found one.  If  DW is not found then -1 is returned.  The position is
                zero-based.

       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexByte (1258   ), IndexChar (1258   ), IndexWord (1260   ), CompareDWord (1227   )


                Listing:  ./refex/ex106.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 6;


                {   Program       t o  d e m o n s t r a t et h e  IndexDWord         f u n c t i o n.  }


                Const
                    A r r a y S i z e=  1 0 0 0 ;
                    MaxValue       =  1 0 0 0 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f DWord     ;
                    I ,J   :   l o n g i n t;
                    K   :  DWord    ;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : =Random     ( MaxValue      ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K := Random     ( MaxValue      ) ;
                       J :=  IndexDWord       ( B u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.98          Indexword

    Synopsis:    Search for a WORD value in a memory range.

Declaration:     function  Indexword(const  buf;len:  SizeInt;b:  Word)  :  SizeInt

    Visibility:   default

Description:     IndexChar  searches  the  memory  at  buf  for  maximally  len  positions  for  the  Word  W  and
                returns it's position if it found one.  If  W is not found then -1 is returned.

       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexByte (1258   ), IndexDWord (1259   ), IndexChar (1258   ), CompareWord (1228   )


                Listing:  ./refex/ex107.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 7;


                {   Program       t o  d e m o n s t r a t et h e  I n d e x W o r d f u n c t i o n. }



                                                                                1260

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________


                Const
                    A r r a y S i z e=  1 0 0 0 ;
                    MaxValue       =  1 0 0 0 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f  Word   ;
                    I ,J   :   l o n g i n t;
                    K   :  Word   ;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : =Random     ( MaxValue      ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K := Random     ( MaxValue      ) ;
                       J :=  I n d e x W o r(dB u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.99          InitCriticalSection

    Synopsis:    Initialize a critical section

Declaration:     procedure  InitCriticalSection(var  cs:  TRTLCriticalSection)

    Visibility:   default

Description:     InitCriticalSection initializes a critical section CS for use.  Before using a critical section
                with EnterCriticalsection (1237   ) or LeaveCriticalsection (1267   ) the critical section should be
                initialized with InitCriticalSection.

                When a critical section is no longer used, it should be disposed of with DoneCriticalsection
                (1235   )

    See also:    DoneCriticalsection (1235   ), EnterCriticalsection (1237   ), LeaveCriticalsection (1267   )
                29.9.100           InitThread

    Synopsis:    Initialize a thread

Declaration:     procedure  InitThread(stklen:  SizeUInt)

    Visibility:   default

Description:     Do not use, this is used internally by the thread manager.
                29.9.101           InitThreadVars

    Synopsis:    Initialize threadvars

Declaration:     procedure  InitThreadVars(RelocProc:  Pointer)



                                                                                1261

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     This routine should be called when threading is started.  It is called by the compiler and
                should never be called manually, only from a thread manager.

       Errors:   None.

    See also:    TThreadManager (1205   ), TThreadManager.InitThreadVar (1205   )
                29.9.102           Insert

    Synopsis:    Insert one string in another.

Declaration:     procedure  Insert(const  source:  shortstring;var  s:  shortstring;
                                           index:  SizeInt)
                procedure  Insert(source:  Char;var  s:  shortstring;index:  SizeInt)
                procedure  Insert(const  Source:  AnsiString;var  S:  AnsiString;
                                           Index:  SizeInt)
                procedure  Insert(const  Source:  WideString;var  S:  WideString;
                                           Index:  SizeInt)

    Visibility:   default

Description:     Insert  inserts  string  Source  in  string  S,  at  position  Index,  shifting  all  characters  after
                Index to the right.  The resulting string is truncated at 255 characters, if needed.  (i.e.  for
                shortstrings)

       Errors:   None.

    See also:    Delete (1233   ), Copy (1230   ), Pos (1301   )


                Listing:  ./refex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  I n s e r t f u n c t i o n.  }


                Var    S   :   S t r i n g;


                 b e g i n
                    S :=  'F r e e  P a s c a l i s  d i f f i c u l t t o  u s e  ! ';
                    I n s e r t ( 'NOT     ' ,S , pos  ( ' d i f f i c u l't,S  ) ) ;
                    w r i t e l n ( s ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.103           int

    Synopsis:    Calculate integer part of floating point value.

Declaration:     function  int(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Int returns the integer part of any Real X, as a Real.

       Errors:   None.

    See also:    Frac (1248   ), Round (1311   )



                                                                                1262

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                Listing:  ./refex/ex34.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 4;


                {   Program       t o  d e m o n s t r a t et h e  I n t  f u n c t i o n. }


                 b e g i n
                    W r i t e l n ( I n t( 1 2 3 . 4 5 6 ) : 0 : 1 ) ;{   P r i n t s   1 2 3 . 0 }
                    W r i t e l n ( I n t( - 1 2 3 . 4 5 6 ) : 0 : 1 ){;  P r i n t s - 1 2 3 . 0 }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.104           InterlockedCompareExchange

    Synopsis:    Conditional exchange

Declaration:     function  InterlockedCompareExchange(var  Target:  LongInt;
                                                                          NewValue:  LongInt;Comperand:  LongInt)
                                                                            :  LongInt
                function  InterlockedCompareExchange(var  Target:  Pointer;
                                                                          NewValue:  Pointer;Comperand:  Pointer)
                                                                            :  Pointer

    Visibility:   default

Description:     InterlockedCompareExchange  does  an  compare-and-exchange  operation  on  the  specified
                values in a thread-safe way.  The function compares Target and Comparand and exchanges
                Target  with  NewValue  if  Target  and  Comparand  are  equal.   It  returns  the  old  value  of
                Target.  This is done in a thread-safe way, i.e., only one processor is accessing the Target
                variable at a time.

       Errors:   None.

    See also:    InterLockedDecrement (1263   ), InterLockedIncrement (1264   ), InterLockedExchange (1264   ),
                InterLockedExchangeAdd (1264   )
                29.9.105           InterLockedDecrement

    Synopsis:    Thread-safe decrement

Declaration:     function  InterLockedDecrement(var  Target:  LongInt)  :  LongInt
                function  InterLockedDecrement(var  Target:  Pointer)  :  Pointer

    Visibility:   default

Description:     InterLockedDecrement decrements Target with 1 and returns the result.  This is done in
                a thread-safe way.  (i.e.  only one processor is accessing the variable at a time).

       Errors:   None.

    See also:    InterLockedIncrement (1264   ), InterLockedExchange (1264   ), InterLockedExchangeAdd (1264   ),
                InterlockedCompareExchange (1263   )

                                                                                1263

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.106           InterLockedExchange

    Synopsis:    Exchange 2 integers in a thread-safe way

Declaration:     function  InterLockedExchange(var  Target:  LongInt;Source:  LongInt)
                                                                :  LongInt
                function  InterLockedExchange(var  Target:  Pointer;Source:  Pointer)
                                                                :  Pointer

    Visibility:   default

Description:     InterLockedExchange stores Source in Target and returns the old value of  Target.  This
                is done in a thread-safe way,  i.e.,  only one processor is accessing the Target variable at a
                time.

       Errors:   None.

    See also:    InterLockedDecrement (1263   ), InterLockedIncrement (1264   ), InterLockedExchangeAdd (1264   ),
                InterlockedCompareExchange (1263   )
                29.9.107           InterLockedExchangeAdd

    Synopsis:    Thread-safe add and exchange of 2 values

Declaration:     function  InterLockedExchangeAdd(var  Target:  LongInt;Source:  LongInt)
                                                                     :  LongInt
                function  InterLockedExchangeAdd(var  Target:  Pointer;Source:  Pointer)
                                                                     :  Pointer

    Visibility:   default

Description:     InterlockedDecrement  adds  to  Target  the  value  of  Source  in  a  thread-safe  way,  and
                returns the old value of  Target.This is done in a thread-safe way, i.e., only one processor is
                accessing the Target variable at a time.

       Errors:   None.

    See also:    InterLockedDecrement (1263   ), InterLockedIncrement (1264   ), InterLockedExchange (1264   ),
                InterlockedCompareExchange (1263   )
                29.9.108           InterLockedIncrement

    Synopsis:    Thread-safe increment

Declaration:     function  InterLockedIncrement(var  Target:  LongInt)  :  LongInt
                function  InterLockedIncrement(var  Target:  Pointer)  :  Pointer

    Visibility:   default

Description:     InterLockedIncrement increments Target with 1 and returns the result.  This is done in
                a thread-safe way (i.e.  only one processor is accessing the variable at a time).

       Errors:   None.

    See also:    InterLockedDecrement (1263   ), InterLockedExchange (1264   ), InterLockedExchangeAdd (1264   ),
                InterlockedCompareExchange (1263   )



                                                                                1264

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.109           IOResult

    Synopsis:    Return result of last file IO operation

Declaration:     function  IOResult  :  Word

    Visibility:   default

Description:     IOresult contains the result of any input/output call, when the {\$i-} compiler directive is
                active, disabling IO checking.  When the flag is read, it is reset to zero.  If  IOresult is zero,
                the operation completed successfully.  If non-zero,  an error occurred.  The following errors
                can occur:

                dos errors :


                2 File not found.

                3 Path not found.

                4 Too many open files.

                5 Access denied.

                6 Invalid file handle.

                12  Invalid file-access mode.

                15  Invalid disk number.

                16  Cannot remove current directory.

                17  Cannot rename across volumes.


                I/O errors :


                100   Error when reading from disk.

                101   Error when writing to disk.

                102   File not assigned.

                103   File not open.

                104   File not opened for input.

                105   File not opened for output.

                106   Invalid number.


                Fatal errors :


                150   Disk is write protected.

                151   Unknown device.

                152   Drive not ready.

                153   Unknown command.

                154   CRC check failed.

                155   Invalid drive specified..

                156   Seek error on disk.

                157   Invalid media type.

                158   Sector not found.

                159   Printer out of paper.

                160   Error when writing to device.

                161   Error when reading from device.



                                                                                1265

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                162  Hardware failure.


       Errors:   None.


                Listing:  ./refex/ex35.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   Program       t o  d e m o n s t r a t et h e  I O R e s u l t f u n c t i o n. }


                Var    F   :   t e x t;


                 b e g i n
                    A s s i g n ( f ,p a r a m s t r( 1 ) ) ;
                    { $ i- }
                    R e s e t ( f ) ;
                    { $ i+ }
                    I f  I O r e s u l t<>0   then
                        w r i t e l n(  'F i l e  ' ,p a r a m s t r( 1 ) ,'  d o e s n'' t  e x i s t' )
                    e l s e
                        w r i t e l n(  'F i l e  ' ,p a r a m s t r( 1 ) ,'  e x i s t s') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.110           IsMemoryManagerSet

    Synopsis:    Is the memory manager set

Declaration:     function  IsMemoryManagerSet  :  Boolean

    Visibility:   default

Description:     IsMemoryManagerSet will return True if the memory manager has been set to another value
                than the system heap manager, it will return False otherwise.

       Errors:   None.

    See also:    SetMemoryManager (1318   ), GetMemoryManager (1251   )
                29.9.111           KillThread

    Synopsis:    Kill a running thread

Declaration:     function  KillThread(threadHandle:  TThreadID)  :  DWord

    Visibility:   default

Description:     KillThread causes a running thread to be aborted.  The thread is identified by it's handle
                or ID threadHandle.

                The function returns zero if succesful.  A nonzero return value indicates failure.

       Errors:   If a failure occurred, a nonzero result is returned.  The meaning is system dependent.

    See also:    WaitForThreadTerminate (1339   ), EndThread (1236   ), SuspendThread (1328   )


                                                                                1266

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.112           LeaveCriticalsection

    Synopsis:    Leave a critical section

Declaration:     procedure  LeaveCriticalsection(var  cs:  TRTLCriticalSection)

    Visibility:   default

Description:     LeaveCriticalSection signals that the current thread is exiting the critical section CS it
                has entered with EnterCriticalSection (1237   ).

                The critical section must have been initialized with InitCriticalSection (1261   ) prior to a call
                to EnterCriticalsection and LeaveCriticalSection.

    See also:    InitCriticalsection (1261   ), DoneCriticalsection (1235   ), EnterCriticalsection (1237   )
                29.9.113           Length

    Synopsis:    Calculate length of a string.

Declaration:     function  Length(S:  AStringType)  :  Integer
                function  Length(A:  DynArrayType)  :  Integer

    Visibility:   default

Description:     Length returns the length of the string  S, which is limited to 255 for shortstrings.  If the
                strings S is empty, 0 is returned.

                Note:  The length of the string S is stored in S[0] for shortstrings only.  The Length fuction
                should always be used on ansistrings and widestrings.

                For dynamical arrays, the function returns the number of elements in the array.

       Errors:   None.

    See also:    Pos (1301   )


                Listing:  ./refex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  d e m o n s t r a t et h e  L e n g t h f u n c t i o n.  }


                Var    S   :   S t r i n g;
                        I  :   I n t e g e r;


                 b e g i n
                    S :=  '' ;
                    f o r  i : = 1  t o  1 0  do
                        b e g i n
                       S :=  S+  '* ' ;
                        W r i t e l n( Length     (S ) : 2 ,'   :  ' , s ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                1267

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.114           LEtoN

    Synopsis:    Convert Little Endian-ordered integer to Native-ordered integer

Declaration:     function  LEtoN(const  AValue:  SmallInt)  :  SmallInt
                function  LEtoN(const  AValue:  Word)  :  Word
                function  LEtoN(const  AValue:  LongInt)  :  LongInt
                function  LEtoN(const  AValue:  DWord)  :  DWord
                function  LEtoN(const  AValue:  Int64)  :  Int64
                function  LEtoN(const  AValue:  QWord)  :  QWord

    Visibility:   default

Description:     LEToN will rearrange the bytes in a Little-Endian number to the native order for the current
                processor.   That  is,  for  a  little-endian  processor,  it  will  do  nothing,  and  for  a  big-endian
                processor, it will invert the order of the bytes.

    See also:    BEtoN (1219   ), NtoBE (1273   ), NtoLE (1273   )
                29.9.115           ln

    Synopsis:    Calculate logarithm

Declaration:     function  ln(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Ln returns the natural logarithm of the Real parameter X. X must be positive.

       Errors:   An run-time error will occur when X is negative.

    See also:    Exp (1242   ), Power (1165   )


                Listing:  ./refex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   Program       t o  d e m o n s t r a t et h e  Ln   f u n c t i o n.  }


                 b e g i n
                    W r i t e l n ( Ln ( 1 ) ) ;          {   P r i n t s 0  }
                    W r i t e l n ( Ln ( Exp  ( 1 ) ) ) ; {   P r i n t s 1  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.116           lo

    Synopsis:    Return low byte/word of value.

Declaration:     function  lo(B:  Byte)  :  Byte
                function  lo(i:  Integer)  :  Byte
                function  lo(w:  Word)  :  Byte
                function  lo(l:  LongInt)  :  Word
                function  lo(l:  DWord)  :  Word
                function  lo(i:  Int64)  :  DWord
                function  lo(q:  QWord)  :  DWord

    Visibility:   default
                                                                                1268

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     Lo returns the low byte of its argument if this is of type Integer or Word.  It returns the
                low word of its argument if this is of type Longint or Cardinal.

       Errors:   None.

    See also:    Ord (1299   ), Chr (1223   ), Hi (1254   )


                Listing:__./refex/ex38.pp__________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 3 8;


                {   Program       t o  d e m o n s t r a t et h e  Lo   f u n c t i o n.  }


                Var    L   :   L o n g i n t;
                       W   :  Word    ;


                 b e g i n
                    L : = ( 1 S h l  1 6 )  +  ( 1   S h l  4 ) ;    {  $10010      }
                    W r i t e l n ( Lo ( L ) ) ;                     {  P r i n t s 1 6   }
                   W  : = ( 1 S h l  8 )  +  ( 1   S h l  4 ) ;      {  $110        }
                    W r i t e l n ( Lo (W  ) ) ;                     {  P r i n t s 1 6   }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.117           LoadResource

    Synopsis:    Load a resource for use

Declaration:     function  LoadResource(ModuleHandle:  HMODULE;ResHandle:  TResourceHandle)
                                                     :  HGLOBAL

    Visibility:   default

Description:     LoadResource loads a resource identified by ResHandle from a module identified by ModuleHandleinto
                memory.  It returns a handle to the resource.

                Loaded resources must be unloaded again using the FreeResource (1249   ) function.

       Errors:   On error, 0 is returned.

    See also:    FindResource  (1246   ),  FreeResource  (1249   ),  SizeofResource  (1322   ),  LockResource  (1269   ),
                UnlockResource (1335   ), FreeResource (1249   )
                29.9.118           LockResource

    Synopsis:    Lock a resource

Declaration:     function  LockResource(ResData:  HGLOBAL)  :  Pointer

    Visibility:   default

Description:     LockResource  locks  a  resource  previously  loaded  by  LoadResource  into  memory.   This
                means  that  any  attempt  to  modify  the  resource  will  fail  while  it  is  locked.   The  function
                returns a pointer to the resource location in memory.

                The resource can be freed again using the UnlockResource (1335   ) function.

       Errors:   if the function fails, Nil is returned.

    See also:    FindResource  (1246   ),  FreeResource  (1249   ),  SizeofResource  (1322   ),  LoadResource  (1269   ),
                UnlockResource (1335   ), FreeResource (1249   )



                                                                                1269

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.119           longjmp

    Synopsis:    Jump to address.

Declaration:     procedure  longjmp(var  S:  jmp_buf;value:  LongInt)

    Visibility:   default

Description:     LongJmp jumps to the adress in the envjmp_buf, and restores the registers that were stored
                in it at the corresponding SetJmp (1316   ) call.  In effect, program flow will continue at the
                SetJmp call, which will return value instead of 0.  If a value equal to zero is passed, it will
                be  converted  to  1  before  passing  it  on.  The  call  will  not  return,  so  it  must  be  used  with
                extreme care.  This can be used for error recovery,  for instance when a segmentation fault
                occurred.

                For an example, see SetJmp (1316   )

       Errors:   None.

    See also:    SetJmp (1316   )
                29.9.120           Low

    Synopsis:    Return lowest index of open array or enumerated

Declaration:     function  Low(Arg:  TypeOrVariable)  :  TOrdinal

    Visibility:   default

Description:     The return value of  Low depends on it's argument:


                     1.If  the  argument  is  an  ordinal  type,  Low  returns  the  lowest  value  in  the  range  of  the
                       given ordinal type.

                     2.If the argument is an array type or an array type variable then Low returns the lowest
                       possible value of it's index.

                     3.If the argument is an open array identifier in a function or procedure, then Low returns
                       the lowest element of the array, which is always zero.

                     4.If the argument is a set type then it returns the lowest value of the underlying ordinal
                       type.


                The return type is always the same type as the type of the argument.

                for an example, see High (1255   ).

       Errors:   None.

    See also:    High (1255   ), Ord (1299   ), Pred (1302   ), Succ (1327   )
                29.9.121           lowerCase

    Synopsis:    Return lowercase version of a string.

Declaration:     function  lowerCase(const  s:  shortstring)  :  shortstring;    Overload
                function  lowerCase(c:  Char)  :  Char;    Overload
                function  lowercase(const  s:  ansistring)  :  ansistring

    Visibility:   default

                                                                                1270

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     Lowercase returns the lowercase version of its argument C. If its argument is a string, then
                the complete string is converted to lowercase.  The type of the returned value is the same as
                the type of the argument.

       Errors:   None.

    See also:    Upcase (1335   )


                Listing:  ./refex/ex73.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 7 3;


                {   Program       t o  d e m o n s t r a t et h e  L o w e r c a s e f u n c t i o n. }


                 v a r c : c h a r;


                 b e g i n
                    f o r  c :=  'A '  t o   'Z '  do
                        w r i t e(l o w e r c a s e(c) ) ;
                    W r i t e l n;
                    W r i t e l n(Lowercase       ( 'ABCDEFGHIJKLMNOPQRSTUVWXYZ                    ') ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.122           MemSize

    Synopsis:    Return the size of a memory block.

Declaration:     function  MemSize(p:  pointer)  :  PtrInt

    Visibility:   default

Description:     MemSize returns the size of a memory block on the heap.

       Errors:   Passing an invalid pointer may lead to run-time errors (access violations).

    See also:    GetMem (1251   ), FreeMem (1248   )
                29.9.123           mkdir

    Synopsis:    Create a new directory.

Declaration:     procedure  mkdir(const  s:  String)

    Visibility:   default

Description:     Mkdir creates a new directory S.

                For an example, see Rmdir (1310   ).

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Chdir (1222   ), Rmdir (1310   )
                                                                                1271

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.124           Move

    Synopsis:    Move data from one location in memory to another

Declaration:     procedure  Move(const  source;var  dest;count:  SizeInt)

    Visibility:   default

Description:     Move moves Count bytes from Source to Dest.

       Errors:   If either Dest or Source is outside the accessible memory for the process, then a run-time
                error will be generated.

    See also:    Fillword (1246   ), Fillchar (1245   )


                Listing:  ./refex/ex42.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 2;


                {   Program       t o  d e m o n s t r a t et h e  Move     f u n c t i o n. }


                Var    S1  , S2   :   S t r i n g [ 3 0 ] ;


                 b e g i n
                    S1 :=  ' H e l l o World      ! ';
                    S2 :=  ' Bye  ,  b y e        ! ';
                    Move     (S1  , S2 , S i z e o f(S1  ) ) ;
                    W r i t e l n ( S2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.125           MoveChar0

    Synopsis:    Move data till first zero character

Declaration:     procedure  MoveChar0(const  buf1;var  buf2;len:  SizeInt)

    Visibility:   default

Description:     MoveChar0 moves Count bytes from Src to Dest,  and stops moving if a zero character is
                found.

       Errors:   No checking is done to see if  Count stays within the memory allocated to the process.

    See also:    Move (1272   )


                Listing:  ./refex/ex109.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 9;


                {   Program       t o  d e m o n s t r a t et h e  MoveChar0         f u n c t i o n. }


                Var
                    Buf1   , Buf2     :  A r r a y[ 1 . . 8 0 ] o f  c h a r;
                    I   :  l o n g i n t;


                 b e g i n
                    Randomize       ;
                    For    I := low  ( b u f 1)   t o  h i g h( b u f 1)  do
                       Buf1    [i ] : =c h r( Random     (16)+   Ord   ( 'A ' ) ) ;



                                                                                1272

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    W r i t e l n(' O r i g i n a l b u f f e r') ;
                    w r i t e l n(Buf1   ) ;
                    Buf1   [Random     ( 8 0 ) + 1 ] : = # 0 ;
                    MoveChar0       (Buf1    ,Buf2   , 8 0 ) ;
                    W r i t e l n(' Randomly       z e r o- t e r m i n a t e dB u f f e r' ) ;
                    W r i t e l n(Buf2   ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.126           New

    Synopsis:    Dynamically allocate memory for variable

Declaration:     procedure  New(var  P:  Pointer)
                procedure  New(var  P:  Pointer;Cons:  TProcedure)

    Visibility:   default

Description:     New allocates a new instance of the type pointed to by P, and puts the address in P. If P is
                an object, then it is possible to specify the name of the constructor with which the instance
                will be created.

                For an example, see Dispose (1234   ).

       Errors:   If not enough memory is available, Nil will be returned.

    See also:    Dispose (1234   ), Freemem (1248   ), Getmem (1251   )
                29.9.127           NtoBE

    Synopsis:    Convert Native-ordered integer to a Big Endian-ordered integer

Declaration:     function  NtoBE(const  AValue:  SmallInt)  :  SmallInt
                function  NtoBE(const  AValue:  Word)  :  Word
                function  NtoBE(const  AValue:  LongInt)  :  LongInt
                function  NtoBE(const  AValue:  DWord)  :  DWord
                function  NtoBE(const  AValue:  Int64)  :  Int64
                function  NtoBE(const  AValue:  QWord)  :  QWord

    Visibility:   default

Description:     NToBE will rearrange the bytes in a natively-ordered number to the Big-Endian order.  That
                is,  for  a  Little-Endian  processor,  it  will  invert  the  order  of  the  bytes  and  for  a  big-endian
                processor, it will do nothing.

    See also:    BEtoN (1219   ), LEtoN (1268   ), NtoLE (1273   )
                29.9.128           NtoLE

    Synopsis:    Convert Native-ordered integer to a Little Endian-ordered integer

Declaration:     function  NtoLE(const  AValue:  SmallInt)  :  SmallInt
                function  NtoLE(const  AValue:  Word)  :  Word
                function  NtoLE(const  AValue:  LongInt)  :  LongInt
                function  NtoLE(const  AValue:  DWord)  :  DWord
                function  NtoLE(const  AValue:  Int64)  :  Int64
                function  NtoLE(const  AValue:  QWord)  :  QWord



                                                                                1273

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     NToLE will rearrange the bytes in a natively-ordered number to the little-Endian order.  That
                is, for a Big-Endian processor, it will invert the order of the bytes and for a Little-Endian
                processor, it will do nothing.

    See also:    BEtoN (1219   ), LEtoN (1268   ), NtoBE (1273   )
                29.9.129           Null

    Synopsis:    Null variant

Declaration:     function  Null  :  Variant

    Visibility:   default
                29.9.130           OctStr

    Synopsis:    Convert integer to a string with octal representation.

Declaration:     function  OctStr(Val:  LongInt;cnt:  Byte)  :  shortstring
                function  OctStr(Val:  Int64;cnt:  Byte)  :  shortstring
                function  OctStr(Val:  qword;cnt:  Byte)  :  shortstring

    Visibility:   default

Description:     OctStr returns a string with the octal representation of Value.  The string has exactly cnt
                charaters.

       Errors:   None.

    See also:    Str (1325   ), Val (1337   ), BinStr (1219   ), HexStr (1254   )


                Listing:__./refex/ex112.pp_________________________________________________________________________________________*
 *___________

                Program       e x a m p l e 1 1 2;


                {   Program       t o  d e m o n s t r a t et h e  O c t S t r f u n c t i o n }


                Const      V a l u e =  4 5 6 7 8 ;


                Var     I  :   l o n g i n t;


                 b e g i n
                    For    I : = 1  t o  1 0  do
                        W r i t e l n( O c t S t r(V a l u e, I ) ) ;
                    For    I : = 1  t o  1 6  do
                        W r i t e l n( O c t S t r(I , 3 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.131           odd

    Synopsis:    Is a value odd or even ?

Declaration:     function  odd(l:  LongInt)  :  Boolean
                function  odd(l:  LongWord)  :  Boolean
                function  odd(l:  Int64)  :  Boolean
                function  odd(l:  QWord)  :  Boolean



                                                                                1274

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     Odd returns True if  X is odd, or False otherwise.

       Errors:   None.

    See also:    Abs (1211   ), Ord (1299   )


                Listing:  ./refex/ex43.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 3;


                {   Program       t o  d e m o n s t r a t et h e  Odd    f u n c t i o n. }


                 b e g i n
                    I f  Odd   ( 1 ) Then
                        W r i t e l n(  'E v e r y t h i n gOK   w i t h  1  !  ') ;
                    I f  Not    Odd   ( 2 ) Then
                        W r i t e l n(  'E v e r y t h i n gOK   w i t h  2  !  ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.132           Ofs

    Synopsis:    Return offset of a variable.

Declaration:     function  Ofs(var  X)  :  LongInt

    Visibility:   default

Description:     Ofs  returns  the  offset  of  the  address  of  a  variable.   This  function  is  only  supported  for
                compatibility.  In Free Pascal, it returns always the complete address of the variable, since
                Free Pascal is a 32 bit compiler.

       Errors:   None.

    See also:    DSeg (1235   ), CSeg (1231   ), Seg (1316   ), Ptr (1302   )


                Listing:  ./refex/ex44.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 4;


                {   Program       t o  d e m o n s t r a t et h e  O f s  f u n c t i o n. }


                Var    W   :   P o i n t e r;



                 b e g i n
                   W  := P o i n t e r(Ofs  (W  ) ) ;  {  W   c o n t a i n s i t s own     o f f s e t. }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.133           operator  *(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  *(variant,  variant):  variant(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  variant



                                                                                1275

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:

       Errors:
                29.9.134           operator  **(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  **(variant,  variant):  variant(const  op1:  variant;
                                                                                              const  op2:  variant)
                                                                                               :  variant

    Visibility:   default

Description:

       Errors:
                29.9.135           operator  +(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  +(variant,  variant):  variant(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  variant

    Visibility:   default

Description:

       Errors:
                29.9.136           operator  -(variant):  variant

    Synopsis:

Declaration:     function  operator  -(variant):  variant(const  op:  variant)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.137           operator  -(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  -(variant,  variant):  variant(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  variant

    Visibility:   default

Description:

       Errors:



                                                                                1276

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.138           operator  /(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  /(variant,  variant):  variant(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  variant

    Visibility:   default

Description:

       Errors:
                29.9.139           operator  :=(ansistring):  olevariant

    Synopsis:

Declaration:     function  operator  :=(ansistring):  olevariant(const  source:  ansistring)
                                                                                          :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.140           operator  :=(ansistring):  variant

    Synopsis:

Declaration:     function  operator  :=(ansistring):  variant(const  source:  ansistring)
                                                                                     :  variant

    Visibility:   default

Description:

       Errors:
                29.9.141           operator  :=(Boolean):  olevariant

    Synopsis:

Declaration:     function  operator  :=(Boolean):  olevariant(const  source:  Boolean)
                                                                                     :  olevariant

    Visibility:   default

Description:

       Errors:


                                                                                1277

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.142           operator  :=(Boolean):  variant

    Synopsis:

Declaration:     function  operator  :=(Boolean):  variant(const  source:  Boolean)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.143           operator  :=(Byte):  olevariant

    Synopsis:

Declaration:     function  operator  :=(Byte):  olevariant(const  source:  Byte)  :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.144           operator  :=(Byte):  variant

    Synopsis:

Declaration:     function  operator  :=(Byte):  variant(const  source:  Byte)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.145           operator  :=(Char):  olevariant

    Synopsis:

Declaration:     function  operator  :=(Char):  olevariant(const  source:  Char)  :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.146           operator  :=(Char):  variant

    Synopsis:

Declaration:     function  operator  :=(Char):  variant(const  source:  Char)  :  variant

    Visibility:   default

Description:

       Errors:



                                                                                1278

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.147           operator  :=(currency):  olevariant

    Synopsis:

Declaration:     function  operator  :=(currency):  olevariant(const  source:  currency)
                                                                                       :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.148           operator  :=(currency):  variant

    Synopsis:

Declaration:     function  operator  :=(currency):  variant(const  source:  currency)
                                                                                  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.149           operator  :=(double):  olevariant

    Synopsis:

Declaration:     function  operator  :=(double):  olevariant(const  source:  double)
                                                                                    :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.150           operator  :=(double):  variant

    Synopsis:

Declaration:     function  operator  :=(double):  variant(const  source:  double)  :  variant

    Visibility:   default

Description:

       Errors:


                                                                                1279

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.151           operator  :=(DWord):  olevariant

    Synopsis:

Declaration:     function  operator  :=(DWord):  olevariant(const  source:  DWord)
                                                                                  :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.152           operator  :=(DWord):  variant

    Synopsis:

Declaration:     function  operator  :=(DWord):  variant(const  source:  DWord)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.153           operator  :=(Int64):  olevariant

    Synopsis:

Declaration:     function  operator  :=(Int64):  olevariant(const  source:  Int64)
                                                                                  :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.154           operator  :=(Int64):  variant

    Synopsis:

Declaration:     function  operator  :=(Int64):  variant(const  source:  Int64)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.155           operator  :=(longbool):  olevariant

    Synopsis:

Declaration:     function  operator  :=(longbool):  olevariant(const  source:  longbool)
                                                                                       :  olevariant

    Visibility:   default

Description:

       Errors:



                                                                                1280

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.156           operator  :=(longbool):  variant

    Synopsis:

Declaration:     function  operator  :=(longbool):  variant(const  source:  longbool)
                                                                                  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.157           operator  :=(LongInt):  olevariant

    Synopsis:

Declaration:     function  operator  :=(LongInt):  olevariant(const  source:  LongInt)
                                                                                     :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.158           operator  :=(LongInt):  variant

    Synopsis:

Declaration:     function  operator  :=(LongInt):  variant(const  source:  LongInt)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.159           operator  :=(olevariant):  ansistring

    Synopsis:

Declaration:     function  operator  :=(olevariant):  ansistring(const  source:  olevariant)
                                                                                          :  ansistring

    Visibility:   default

Description:

       Errors:


                                                                                1281

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.160           operator  :=(olevariant):  Boolean

    Synopsis:

Declaration:     function  operator  :=(olevariant):  Boolean(const  source:  olevariant)
                                                                                     :  Boolean

    Visibility:   default

Description:

       Errors:
                29.9.161           operator  :=(olevariant):  Byte

    Synopsis:

Declaration:     function  operator  :=(olevariant):  Byte(const  source:  olevariant)  :  Byte

    Visibility:   default

Description:

       Errors:
                29.9.162           operator  :=(olevariant):  Char

    Synopsis:

Declaration:     function  operator  :=(olevariant):  Char(const  source:  olevariant)  :  Char

    Visibility:   default

Description:

       Errors:
                29.9.163           operator  :=(olevariant):  currency

    Synopsis:

Declaration:     function  operator  :=(olevariant):  currency(const  source:  olevariant)
                                                                                       :  currency

    Visibility:   default

Description:

       Errors:
                29.9.164           operator  :=(olevariant):  double

    Synopsis:

Declaration:     function  operator  :=(olevariant):  double(const  source:  olevariant)
                                                                                    :  double

    Visibility:   default

Description:

       Errors:



                                                                                1282

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.165           operator  :=(olevariant):  DWord

    Synopsis:

Declaration:     function  operator  :=(olevariant):  DWord(const  source:  olevariant)
                                                                                  :  DWord

    Visibility:   default

Description:

       Errors:
                29.9.166           operator  :=(olevariant):  Int64

    Synopsis:

Declaration:     function  operator  :=(olevariant):  Int64(const  source:  olevariant)
                                                                                  :  Int64

    Visibility:   default

Description:

       Errors:
                29.9.167           operator  :=(olevariant):  longbool

    Synopsis:

Declaration:     function  operator  :=(olevariant):  longbool(const  source:  olevariant)
                                                                                       :  longbool

    Visibility:   default

Description:

       Errors:
                29.9.168           operator  :=(olevariant):  LongInt

    Synopsis:

Declaration:     function  operator  :=(olevariant):  LongInt(const  source:  olevariant)
                                                                                     :  LongInt

    Visibility:   default

Description:

       Errors:
                                                                                1283

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.169           operator  :=(olevariant):  qword

    Synopsis:

Declaration:     function  operator  :=(olevariant):  qword(const  source:  olevariant)
                                                                                  :  qword

    Visibility:   default

Description:

       Errors:
                29.9.170           operator  :=(olevariant):  Real

Declaration:     function  operator  :=(olevariant):  Real(const  source:  olevariant)  :  Real

    Visibility:   default
                29.9.171           operator  :=(olevariant):  ShortInt

    Synopsis:

Declaration:     function  operator  :=(olevariant):  ShortInt(const  source:  olevariant)
                                                                                       :  ShortInt

    Visibility:   default

Description:

       Errors:
                29.9.172           operator  :=(olevariant):  shortstring

    Synopsis:

Declaration:     function  operator  :=(olevariant):  shortstring(const  source:  olevariant)
                                                                                            :  shortstring

    Visibility:   default

Description:

       Errors:
                29.9.173           operator  :=(olevariant):  SmallInt

    Synopsis:

Declaration:     function  operator  :=(olevariant):  SmallInt(const  source:  olevariant)
                                                                                       :  SmallInt

    Visibility:   default

Description:

       Errors:

                                                                                1284

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.174           operator  :=(olevariant):  TDateTime

    Synopsis:

Declaration:     function  operator  :=(olevariant):  TDateTime(const  source:  olevariant)
                                                                                         :  TDateTime

    Visibility:   default

Description:

       Errors:
                29.9.175           operator  :=(olevariant):  TError

    Synopsis:

Declaration:     function  operator  :=(olevariant):  TError(const  source:  olevariant)
                                                                                    :  TError

    Visibility:   default

Description:

       Errors:
                29.9.176           operator  :=(olevariant):  variant

    Synopsis:

Declaration:     function  operator  :=(olevariant):  variant(const  source:  olevariant)
                                                                                     :  variant

    Visibility:   default

Description:

       Errors:
                29.9.177           operator  :=(olevariant):  widechar

    Synopsis:

Declaration:     function  operator  :=(olevariant):  widechar(const  source:  olevariant)
                                                                                       :  widechar

    Visibility:   default

Description:

       Errors:
                                                                                1285

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.178           operator  :=(olevariant):  widestring

    Synopsis:

Declaration:     function  operator  :=(olevariant):  widestring(const  source:  olevariant)
                                                                                          :  widestring

    Visibility:   default

Description:

       Errors:
                29.9.179           operator  :=(olevariant):  Word

    Synopsis:

Declaration:     function  operator  :=(olevariant):  Word(const  source:  olevariant)  :  Word

    Visibility:   default

Description:

       Errors:
                29.9.180           operator  :=(olevariant):  wordbool

    Synopsis:

Declaration:     function  operator  :=(olevariant):  wordbool(const  source:  olevariant)
                                                                                       :  wordbool

    Visibility:   default

Description:

       Errors:
                29.9.181           operator  :=(qword):  olevariant

    Synopsis:

Declaration:     function  operator  :=(qword):  olevariant(const  source:  qword)
                                                                                  :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.182           operator  :=(qword):  variant

    Synopsis:

Declaration:     function  operator  :=(qword):  variant(const  source:  qword)  :  variant

    Visibility:   default

Description:

       Errors:



                                                                                1286

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.183           operator  :=(Real):  olevariant

Declaration:     function  operator  :=(Real):  olevariant(const  source:  Real)  :  olevariant

    Visibility:   default
                29.9.184           operator  :=(Real):  variant

Declaration:     function  operator  :=(Real):  variant(const  source:  Real)  :  variant

    Visibility:   default
                29.9.185           operator  :=(real48):  double

    Synopsis:

Declaration:     function  operator  :=(real48):  double(b:  real48)  :  double

    Visibility:   default

Description:

       Errors:
                29.9.186           operator  :=(ShortInt):  olevariant

    Synopsis:

Declaration:     function  operator  :=(ShortInt):  olevariant(const  source:  ShortInt)
                                                                                       :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.187           operator  :=(ShortInt):  variant

    Synopsis:

Declaration:     function  operator  :=(ShortInt):  variant(const  source:  ShortInt)
                                                                                  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.188           operator  :=(shortstring):  olevariant

    Synopsis:

Declaration:     function  operator  :=(shortstring):  olevariant(const  source:  shortstring)
                                                                                            :  olevariant

    Visibility:   default



                                                                                1287

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:

       Errors:
                29.9.189           operator  :=(shortstring):  variant

    Synopsis:

Declaration:     function  operator  :=(shortstring):  variant(const  source:  shortstring)
                                                                                       :  variant

    Visibility:   default

Description:

       Errors:
                29.9.190           operator  :=(SmallInt):  olevariant

    Synopsis:

Declaration:     function  operator  :=(SmallInt):  olevariant(const  source:  SmallInt)
                                                                                       :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.191           operator  :=(SmallInt):  variant

    Synopsis:

Declaration:     function  operator  :=(SmallInt):  variant(const  source:  SmallInt)
                                                                                  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.192           operator  :=(TDateTime):  olevariant

    Synopsis:

Declaration:     function  operator  :=(TDateTime):  olevariant(const  source:  TDateTime)
                                                                                         :  olevariant

    Visibility:   default

Description:

       Errors:
                                                                                1288

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.193           operator  :=(TDateTime):  variant

    Synopsis:

Declaration:     function  operator  :=(TDateTime):  variant(const  source:  TDateTime)
                                                                                    :  variant

    Visibility:   default

Description:

       Errors:
                29.9.194           operator  :=(TError):  olevariant

    Synopsis:

Declaration:     function  operator  :=(TError):  olevariant(const  source:  TError)
                                                                                    :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.195           operator  :=(TError):  variant

    Synopsis:

Declaration:     function  operator  :=(TError):  variant(const  source:  TError)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.196           operator  :=(variant):  ansistring

    Synopsis:

Declaration:     function  operator  :=(variant):  ansistring(const  source:  variant)
                                                                                     :  ansistring

    Visibility:   default

Description:

       Errors:
                29.9.197           operator  :=(variant):  Boolean

    Synopsis:

Declaration:     function  operator  :=(variant):  Boolean(const  source:  variant)  :  Boolean

    Visibility:   default

Description:

       Errors:



                                                                                1289

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.198           operator  :=(variant):  Byte

    Synopsis:

Declaration:     function  operator  :=(variant):  Byte(const  source:  variant)  :  Byte

    Visibility:   default

Description:

       Errors:
                29.9.199           operator  :=(variant):  Char

    Synopsis:

Declaration:     function  operator  :=(variant):  Char(const  source:  variant)  :  Char

    Visibility:   default

Description:

       Errors:
                29.9.200           operator  :=(variant):  currency

    Synopsis:

Declaration:     function  operator  :=(variant):  currency(const  source:  variant)
                                                                                  :  currency

    Visibility:   default

Description:

       Errors:
                29.9.201           operator  :=(variant):  double

    Synopsis:

Declaration:     function  operator  :=(variant):  double(const  source:  variant)  :  double

    Visibility:   default

Description:

       Errors:
                29.9.202           operator  :=(variant):  DWord

    Synopsis:

Declaration:     function  operator  :=(variant):  DWord(const  source:  variant)  :  DWord

    Visibility:   default

Description:

       Errors:



                                                                                1290

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.203           operator  :=(variant):  Int64

    Synopsis:

Declaration:     function  operator  :=(variant):  Int64(const  source:  variant)  :  Int64

    Visibility:   default

Description:

       Errors:
                29.9.204           operator  :=(variant):  longbool

    Synopsis:

Declaration:     function  operator  :=(variant):  longbool(const  source:  variant)
                                                                                  :  longbool

    Visibility:   default

Description:

       Errors:
                29.9.205           operator  :=(variant):  LongInt

    Synopsis:

Declaration:     function  operator  :=(variant):  LongInt(const  source:  variant)  :  LongInt

    Visibility:   default

Description:

       Errors:
                29.9.206           operator  :=(variant):  olevariant

    Synopsis:

Declaration:     function  operator  :=(variant):  olevariant(const  source:  variant)
                                                                                     :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.207           operator  :=(variant):  qword

    Synopsis:

Declaration:     function  operator  :=(variant):  qword(const  source:  variant)  :  qword

    Visibility:   default

Description:

       Errors:



                                                                                1291

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.208           operator  :=(variant):  Real

Declaration:     function  operator  :=(variant):  Real(const  source:  variant)  :  Real

    Visibility:   default
                29.9.209           operator  :=(variant):  ShortInt

    Synopsis:

Declaration:     function  operator  :=(variant):  ShortInt(const  source:  variant)
                                                                                  :  ShortInt

    Visibility:   default

Description:

       Errors:
                29.9.210           operator  :=(variant):  shortstring

    Synopsis:

Declaration:     function  operator  :=(variant):  shortstring(const  source:  variant)
                                                                                       :  shortstring

    Visibility:   default

Description:

       Errors:
                29.9.211           operator  :=(variant):  SmallInt

    Synopsis:

Declaration:     function  operator  :=(variant):  SmallInt(const  source:  variant)
                                                                                  :  SmallInt

    Visibility:   default

Description:

       Errors:
                29.9.212           operator  :=(variant):  TDateTime

    Synopsis:

Declaration:     function  operator  :=(variant):  TDateTime(const  source:  variant)
                                                                                    :  TDateTime

    Visibility:   default

Description:

       Errors:

                                                                                1292

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.213           operator  :=(variant):  TError

    Synopsis:

Declaration:     function  operator  :=(variant):  TError(const  source:  variant)  :  TError

    Visibility:   default

Description:

       Errors:
                29.9.214           operator  :=(variant):  widechar

    Synopsis:

Declaration:     function  operator  :=(variant):  widechar(const  source:  variant)
                                                                                  :  widechar

    Visibility:   default

Description:

       Errors:
                29.9.215           operator  :=(variant):  widestring

    Synopsis:

Declaration:     function  operator  :=(variant):  widestring(const  source:  variant)
                                                                                     :  widestring

    Visibility:   default

Description:

       Errors:
                29.9.216           operator  :=(variant):  Word

    Synopsis:

Declaration:     function  operator  :=(variant):  Word(const  source:  variant)  :  Word

    Visibility:   default

Description:

       Errors:
                29.9.217           operator  :=(variant):  wordbool

    Synopsis:

Declaration:     function  operator  :=(variant):  wordbool(const  source:  variant)
                                                                                  :  wordbool

    Visibility:   default

Description:

       Errors:



                                                                                1293

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.218           operator  :=(widechar):  olevariant

    Synopsis:

Declaration:     function  operator  :=(widechar):  olevariant(const  source:  widechar)
                                                                                       :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.219           operator  :=(widechar):  variant

    Synopsis:

Declaration:     function  operator  :=(widechar):  variant(const  source:  widechar)
                                                                                  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.220           operator  :=(widestring):  olevariant

    Synopsis:

Declaration:     function  operator  :=(widestring):  olevariant(const  source:  widestring)
                                                                                          :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.221           operator  :=(widestring):  variant

    Synopsis:

Declaration:     function  operator  :=(widestring):  variant(const  source:  widestring)
                                                                                     :  variant

    Visibility:   default

Description:

       Errors:
                                                                                1294

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.222           operator  :=(Word):  olevariant

    Synopsis:

Declaration:     function  operator  :=(Word):  olevariant(const  source:  Word)  :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.223           operator  :=(Word):  variant

    Synopsis:

Declaration:     function  operator  :=(Word):  variant(const  source:  Word)  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.224           operator  :=(wordbool):  olevariant

    Synopsis:

Declaration:     function  operator  :=(wordbool):  olevariant(const  source:  wordbool)
                                                                                       :  olevariant

    Visibility:   default

Description:

       Errors:
                29.9.225           operator  :=(wordbool):  variant

    Synopsis:

Declaration:     function  operator  :=(wordbool):  variant(const  source:  wordbool)
                                                                                  :  variant

    Visibility:   default

Description:

       Errors:
                29.9.226           operator  <(variant,  variant):  Boolean

    Synopsis:

Declaration:     function  operator  <(variant,  variant):  Boolean(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  Boolean

    Visibility:   default



                                                                                1295

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:

       Errors:
                29.9.227           operator  <=(variant,  variant):  Boolean

    Synopsis:

Declaration:     function  operator  <=(variant,  variant):  Boolean(const  op1:  variant;
                                                                                              const  op2:  variant)
                                                                                               :  Boolean

    Visibility:   default

Description:

       Errors:
                29.9.228           operator  =(variant,  variant):  Boolean

    Synopsis:

Declaration:     function  operator  =(variant,  variant):  Boolean(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  Boolean

    Visibility:   default

Description:

       Errors:
                29.9.229           operator  >(variant,  variant):  Boolean

    Synopsis:

Declaration:     function  operator  >(variant,  variant):  Boolean(const  op1:  variant;
                                                                                            const  op2:  variant)
                                                                                              :  Boolean

    Visibility:   default

Description:

       Errors:
                29.9.230           operator  >=(variant,  variant):  Boolean

    Synopsis:

Declaration:     function  operator  >=(variant,  variant):  Boolean(const  op1:  variant;
                                                                                              const  op2:  variant)
                                                                                               :  Boolean

    Visibility:   default

Description:

       Errors:



                                                                                1296

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.231           operator  and(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  and(variant,  variant):  variant(const  op1:  variant;
                                                                                               const  op2:  variant)
                                                                                                 :  variant

    Visibility:   default

Description:

       Errors:
                29.9.232           operator  div(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  div(variant,  variant):  variant(const  op1:  variant;
                                                                                               const  op2:  variant)
                                                                                                 :  variant

    Visibility:   default

Description:

       Errors:
                29.9.233           operator  mod(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  mod(variant,  variant):  variant(const  op1:  variant;
                                                                                               const  op2:  variant)
                                                                                                 :  variant

    Visibility:   default

Description:

       Errors:
                29.9.234           operator  not(variant):  variant

    Synopsis:

Declaration:     function  operator  not(variant):  variant(const  op:  variant)  :  variant

    Visibility:   default

Description:

       Errors:
                                                                                1297

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.235           operator  or(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  or(variant,  variant):  variant(const  op1:  variant;
                                                                                              const  op2:  variant)
                                                                                               :  variant

    Visibility:   default

Description:

       Errors:
                29.9.236           operator  shl(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  shl(variant,  variant):  variant(const  op1:  variant;
                                                                                               const  op2:  variant)
                                                                                                 :  variant

    Visibility:   default

Description:

       Errors:
                29.9.237           operator  shr(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  shr(variant,  variant):  variant(const  op1:  variant;
                                                                                               const  op2:  variant)
                                                                                                 :  variant

    Visibility:   default

Description:

       Errors:
                29.9.238           operator  xor(variant,  variant):  variant

    Synopsis:

Declaration:     function  operator  xor(variant,  variant):  variant(const  op1:  variant;
                                                                                               const  op2:  variant)
                                                                                                 :  variant

    Visibility:   default

Description:

       Errors:

                                                                                1298

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.239           Ord

    Synopsis:    Return ordinal value of an ordinal type.

Declaration:     function  Ord(X:  TOrdinal)  :  LongInt

    Visibility:   default

Description:     Ord returns the Ordinal value of a ordinal-type variable X.

                Historical note:

                Originally,  Pascal did not have typecasts and ord was a necessary function in order to do
                certain  operations  on  non-integer  ordinal  types.  With  the  arrival  of  typecasting  a  generic
                approach  became  possible,  making  ord  mostly  obselete.   However  ord  is  not  considered
                deprecated and remains in wide use today.

       Errors:   None.

    See also:    Chr (1223   ), Succ (1327   ), Pred (1302   ), High (1255   ), Low (1270   )


                Listing:  ./refex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  Ord  , Pred   , S u c c  f u n c t i o n.s  }


                Type
                    TEnum     =  (  Zero   ,  One   ,  Two  ,   Three    ,  F o u r) ;


                Var
                    X   :  L o n g i n t;
                    Y   :  TEnum    ;


                 b e g i n
                    X : = 1 2 5 ;
                    W r i t e l n ( Ord  (X  ) ) ;   {   P r i n t s 1 2 5  }
                    X := Pred   ( X ) ;
                    W r i t e l n ( Ord  (X  ) ) ;   {   p r i n t s 1 2 4  }
                    Y : =  One  ;
                    W r i t e l n ( Ord  ( y ) ) ;   {   P r i n t s 1  }
                    Y := Succ   ( Y ) ;
                    W r i t e l n ( Ord  (Y  ) ) ;   {   P r i n t s2 }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.240           Paramcount

    Synopsis:    Return number of command-line parameters passed to the program.

Declaration:     function  Paramcount  :  LongInt

    Visibility:   default

Description:     Paramcount returns the number of command-line arguments.  If no arguments were given
                to the running program, 0 is returned.

       Errors:   None.

    See also:    Paramstr (1300   )

                                                                                1299

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                Listing:  ./refex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 6;


                {   Program       t o  d e m o n s t r a t et h e  ParamCount         and    P a r a m S t r f u n c t i o n s. }
                Var
                    I   :  L o n g i n t;


                 b e g i n
                    W r i t e l n ( p a r a m s t r( 0 ) ,' :   Got    ' ,ParamCount        , ' command     -  l i n e p a r a m e *
 *t e r s:  ') ;
                    For    i : = 1  t o  ParamCount         do
                        W r i t e l n( ParamStr        ( i ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.241           ParamStr

    Synopsis:    Return value of a command-line argument.

Declaration:     function  ParamStr(l:  LongInt)  :  String

    Visibility:   default

Description:     Paramstr returns the L-th command-line argument.  L must be between 0 and Paramcount,
                these values included.  The zeroth argument is the path and file name with which the program
                was started.

                The command-line parameters will be truncated to a length of 255, even though the operating
                system  may  support  bigger  command-lines.   The  Objpas  unit  (used  in  objfpc  or  delphi
                mode) defines versions of  Paramstr which return the full-length command-line arguments,
                using ansistrings.

                In the interest of portability, the ParamStr function tries to behave the same on all operating
                systems:  like  the  original  ParamStr  function  in  Turbo  Pascal.  This  means  even  on  Unix,
                paramstr(0)  returns  the  full  path  to  the  program  executable.  A  notable  exception  is  Mac
                OS X, where the return value depends on how the application was started.  It may be that
                just the name of the application is returned (in case of a command-line launch)

                In general, it's a bad idea to rely on the location of the binary.  Often, this goes against best
                OS practices.  Configuration data should (or can) not be stored next to the binary, but on
                designated locations.  What locations these are, is very much operating system dependent.
                Therefore, ParamStr(0) should be used with care.

                For an example, see Paramcount (1299   ).

       Errors:   None.

    See also:    Paramcount (1299   )
                29.9.242           pi

    Synopsis:    Return the value of PI.

Declaration:     function  pi  :  ValReal

    Visibility:   default

Description:     Pi returns the value of Pi (3.1415926535897932385).

       Errors:   None.



                                                                                1300

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    See also:    Cos (1231   ), Sin (1321   )


                Listing:  ./refex/ex47.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   Program       t o  d e m o n s t r a t et h e  P i  f u n c t i o n.  }


                 b e g i n
                    W r i t e l n ( P i) ;                { 3 . 1 4 1 5 9 2 6}
                    W r i t e l n ( S i n( P i) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.243           Pos

    Synopsis:    Search for substring in a string.

Declaration:     function  Pos(const  substr:  shortstring;const  s:  shortstring)  :  SizeInt
                function  Pos(C:  Char;const  s:  shortstring)  :  SizeInt
                function  Pos(const  Substr:  ShortString;const  Source:  AnsiString)
                                      :  SizeInt
                function  pos(const  substr:  shortstring;c:  Char)  :  SizeInt
                function  Pos(const  Substr:  AnsiString;const  Source:  AnsiString)
                                      :  SizeInt
                function  Pos(c:  Char;const  s:  AnsiString)  :  SizeInt
                function  Pos(const  Substr:  WideString;const  Source:  WideString)
                                      :  SizeInt
                function  Pos(c:  Char;const  s:  WideString)  :  SizeInt
                function  Pos(c:  WideChar;const  s:  WideString)  :  SizeInt
                function  Pos(c:  WideChar;const  s:  AnsiString)  :  SizeInt
                function  Pos(c:  AnsiString;const  s:  WideString)  :  SizeInt
                function  Pos(c:  WideString;const  s:  AnsiString)  :  SizeInt
                function  Pos(c:  ShortString;const  s:  WideString)  :  SizeInt
                function  Pos(c:  Char;const  v:  Variant)  :  SizeInt
                function  Pos(s:  ShortString;const  v:  Variant)  :  SizeInt
                function  Pos(a:  AnsiString;const  v:  Variant)  :  SizeInt
                function  Pos(w:  WideString;const  v:  Variant)  :  SizeInt
                function  Pos(v:  Variant;const  c:  Char)  :  SizeInt
                function  Pos(v:  Variant;const  s:  ShortString)  :  SizeInt
                function  Pos(v:  Variant;const  a:  AnsiString)  :  SizeInt
                function  Pos(v:  Variant;const  w:  WideString)  :  SizeInt
                function  Pos(v1:  Variant;const  v2:  Variant)  :  SizeInt

    Visibility:   default

Description:     Pos returns the index of Substr in S, if S contains Substr.  In case Substr isn't found, 0 is
                returned.  The search is case-sensitive.

       Errors:   None

    See also:    Length (1267   ), Copy (1230   ), Delete (1233   ), Insert (1262   )


                Listing:  ./refex/ex48.pp



                                                                                1301

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   Program       t o  d e m o n s t r a t et h e  Pos    f u n c t i o n. }


                Var
                    S   :  S t r i n g;


                 b e g i n
                    S :=  'The    f i r s t s p a c e  i n  t h i s  s e n t e n c e i s  a t  p o s i t i o n :  ' ;
                    W r i t e l n (S  ,pos  (  '  ' ,S ) ) ;
                    S :=  'The    l a s t  l e t t e r o f  t h e  a l p h a b e t d o e s n' 't   a p p e a r i n  t h i s  s e n *
 *t e n c e ';
                    I f  ( Pos    ( 'Z  ',S ) = 0 )  and    ( Pos  ( ' z ', S ) = 0 ) then
                        W r i t e l n( S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.244           Pred

    Synopsis:    Return previous element for an ordinal type.

Declaration:     function  Pred(X:  TOrdinal)  :  TOrdinal

    Visibility:   default

Description:     Pred returns the element that precedes the element that was passed to it.  If it is applied
                to the first value of the ordinal type, and the program was compiled with range checking on
                (\var{\{\$R+\}}, then a run-time error will be generated.

                for an example, see Ord (1299   )

       Errors:   Run-time error 201 is generated when the result is out of range.

    See also:    Ord (1299   ), Pred (1302   ), High (1255   ), Low (1270   )
                29.9.245           prefetch

    Synopsis:    Prefetch a memory location

Declaration:     procedure  prefetch(const  mem)

    Visibility:   default

Description:     Prefetch can be used to optimize the CPU behaviour by already loading a memory location.
                It is mainly used as a hint for those processors that support it.

       Errors:   None.
                29.9.246           ptr

    Synopsis:    Combine segment and offset to pointer

Declaration:     function  ptr(sel:  LongInt;off:  LongInt)  :  farpointer

    Visibility:   default

Description:     Ptr returns a pointer, pointing to the address specified by segment Sel and offset Off.

 Remark:
                                                                                1302

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                     1.In the 32-bit flat-memory model supported by Free Pascal, this function is obsolete.

                     2.The returned address is simply the offset.

       Errors:   None.

    See also:    Addr (1213   )


                Listing:  ./refex/ex59.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 9;


                {   Program       t o  d e m o n s t r a t et h e  P t r  ( c o m p a b i l i t)y  f u n c t i o n.
                }


                 t y p e p S t r i n g =  ^  S t r i n g;


                Var    P   :   p S t r i n g;
                       S   :   S t r i n g;


                 b e g i n
                    S :=  'H e l l o,  World      ! ';
                    P := p S t r i n g(P t r( Seg  ( S ) ,L o n g i n t(Ofs   (S ) ) ) ) ;
                    {P   now    p o i n t s t o  S   ! }
                    W r i t e l n (P  ^ ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.247           RaiseList

    Synopsis:    List of currently raised exceptions.

Declaration:     function  RaiseList  :  PExceptObject

    Visibility:   default

Description:     RaiseList returns a pointer to the list of currently raised exceptions (i.e.  a pointer to the
                first exception block.

       Errors:
                29.9.248           Random

    Synopsis:    Generate random number

Declaration:     function  Random(l:  LongInt)  :  LongInt
                function  Random(l:  Int64)  :  Int64
                function  Random  :  extended

    Visibility:   default

Description:     Random returns a random number larger or equal to 0 and strictly less than L. If the argument
                L is omitted, a Real number between 0 and 1 is returned.  (0 included, 1 excluded)

       Errors:   None.

    See also:    Randomize (1304   )


                Listing:  ./refex/ex49.pp



                                                                                1303

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   Program       t o  d e m o n s t r a t et h e  Random      and    Randomize         f u n c t i o n s. }


                Var     I, Count    , g u e s s :  L o n g i n t;
                       R   :   R e a l;


                 b e g i n
                    Randomize       ;  {   T h i s way    we    g e n e r a t ea   new    s e q u e n c e e v e r y t i m e
                                           t h e  p r o g r a m i s  r u n}
                    Count    : = 0 ;
                    For    i : = 1  t o  1 0 0 0 do
                        I f Random     > 0 . 5  then     i n c( Count    ) ;
                    W r i t e l n ( ' G e n e r a t e d' ,Count    , '  numbers       >  0 . 5 ' ) ;
                    W r i t e l n ( 'o u t   o f 1 0 0 0  g e n e r a t e d numbers     . ' ) ;
                    c o u n t: = 0 ;
                    For    i : = 1  t o  5  do
                        b e g i n
                        w r i t e ( 'G u e s s  a  number       b e t w e e n1   and    5  :   ' ) ;
                        r e a d l n(G u e s s) ;
                        I f  G u e s s=Random     ( 5 ) + 1 then     i n c( c o u n t) ;
                       end   ;
                    W r i t e l n ( 'You     g u e s s e d ', Count    , '  o u t  o f  5   c o r r e c t.') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.249           Randomize

    Synopsis:    Initialize random number generator

Declaration:     procedure  Randomize

    Visibility:   default

Description:     Randomize  initializes  the  random  number  generator  of  Free  Pascal,  by  giving  a  value  to
                Randseed, calculated with the system clock.

                For an example, see Random (1303   ).

       Errors:   None.

    See also:    Random (1303   )
                29.9.250           Read

    Synopsis:    Read from a text file into variable

Declaration:     procedure  Read(var  F:  Text;Args:  Arguments)
                procedure  Read(Args:  Arguments)

    Visibility:   default

Description:     Read reads one or more values from a file F, and stores the result in V1, V2, etc.; If no file F
                is specified, then standard input is read.  If F is of type Text, then the variables V1,  V2 etc.
                must be of type Char, Integer, Real, String.  If F is a typed file, then each of the variables
                must  be  of  the  type  specified  in  the  declaration  of  F.  Untyped  files  are  not  allowed  as  an
                argument.

                In  earlier  versions  of  FPC,  it  was  also  allowed  to  read  Pchar  null-terminated  strings,  but
                this has been removed, since there is no buffer checking possible.



                                                                                1304

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
       Errors:   If no data is available, a run-time error is generated.  This behavior can be controlled with
                the \var{\{\$i\}} compiler switch.

    See also:    Readln (1306   ), Blockread (1220   ), Write (1340   ), Blockwrite (1221   )


                Listing:__./refex/ex50.pp__________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 0;


                {   Program       t o  d e m o n s t r a t et h e  Read   ( Ln )   f u n c t i o n. }


                Var    S   :   S t r i n g;
                       C   :  Char    ;
                       F   :   F i l e o f  c h a r ;


                 b e g i n
                    A s s i g n ( F , 'e x 5 0. pp  ') ;
                    R e s e t ( F ) ;
                    C :=  'A ' ;
                    W r i t e l n ( 'The     c h a r a c t e r sb e f o r e t h e  f i r s t s p a c e  i n  e x 5 0.pp    a r e  :*
 *   ') ;
                    While     not    Eof   ( f)   and   ( C <>  '  ' )  do
                       Begin
                       Read     ( F ,C ) ;
                       Write      (C  ) ;
                       end   ;
                  W r i t e l n;
                  C l o s e  (F ) ;
                  W r i t e l n ( ' Type    some     w o r d s.  An   empty      l i n e  e n d s  t h e p r o g r a m. ') ;
                  r e p e a t
                      Readln      (S  ) ;
                  u n t i l  S=  '' ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.251           ReadBarrier

    Synopsis:    Memory Read Barrier

Declaration:     procedure  ReadBarrier

    Visibility:   default

Description:     ReadBarrier is a low-level instruction to force a read barrier in the CPU: all memory reads
                before the instruction will be finished before this instruction, before memory reads after the
                instruction occur.

    See also:    ReadDependencyBarrier (1305   ), ReadWriteBarrier (1306   ), WriteBarrier (1341   )
                29.9.252           ReadDependencyBarrier

    Synopsis:    Memory Read Dependency Barrier

Declaration:     procedure  ReadDependencyBarrier

    Visibility:   default

Description:     ReadDependencyBarrier is a low-level instruction to force a read barrier in the CPU: all
                memory reads (loads) depending on previous loads are separate from the ones following the
                instruction.



                                                                                1305

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    See also:    ReadBarrier (1305   ), ReadWriteBarrier (1306   ), WriteBarrier (1341   )
                29.9.253           ReadLn

    Synopsis:    Read from a text file into variable and goto next line

Declaration:     procedure  ReadLn(var  F:  Text;Args:  Arguments)
                procedure  ReadLn(Args:  Arguments)

    Visibility:   default

Description:     Read reads one or more values from a file F, and stores the result in V1, V2, etc.  After that it
                goes to the next line in the file.  The end of the line is marked by the LineEnding character
                sequence  (which  is  platform  dependent).  The  end-of-line  marker  is  not  considered  part  of
                the line and is ignored.

                If no file F is specified, then standard input is read.  The variables V1,  V2 etc.  must be of
                type Char, Integer, Real, String or PChar.

                For an example, see Read (1304   ).

       Errors:   If no data is available, a run-time error is generated.  This behavior can be controlled with
                the \var{\{\$i\}} compiler switch.

    See also:    Read (1304   ), Blockread (1220   ), Write (1340   ), Blockwrite (1221   )
                29.9.254           ReadWriteBarrier

    Synopsis:    Memory read/write barrier

Declaration:     procedure  ReadWriteBarrier

    Visibility:   default

Description:     ReadWriteBarrier is a low-level instruction to force a read/write barrier in the CPU: both
                read (Loads) and write (stores) operations before and after the barrier are separate.

    See also:    ReadBarrier (1305   ), ReadDependencyBarrier (1305   ), WriteBarrier (1341   )
                29.9.255           Real2Double

    Synopsis:    Convert Turbo Pascal style real to double.

Declaration:     function  Real2Double(r:  real48)  :  double

    Visibility:   default

Description:     The Real2Double function converts a Turbo Pascal style real (6 bytes long) to a native Free
                Pascal double type.  It can be used e.g.  to read old binary TP files with FPC and convert
                them to Free Pacal binary files.

                Note that the assignment operator has been overloaded so a Real48 type can be assigned
                directly to a double or extended.

       Errors:   None.


                Listing:  ./refex/ex110.pp


                                                                                1306

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 1 1 0;


                {   Program       t o  d e m o n s t r a t et h e  R e a l 2 D o u b l ef u n c t i o n. }


                Var
                    i   :  i n t e g e r;
                    R   :  R e a l 4 8;
                    D   :  D o u b l e;
                    E   :  E x t e n d e d;
                    F   :  F i l e  o f  R e a l 4 8;


                 b e g i n
                    A s s i g n(F , ' r e a l s.d a t' ) ;
                    R e s e t( f) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       Read   ( F ,R  ) ;
                       D :=  R e a l 2 D o u b l(eR ) ;
                        W r i t e l n('R e a l  ' ,i , '   :  ' ,D ) ;
                       D := R  ;
                        W r i t e l n('R e a l  ( d i r e c t t o  d o u b l e)    ' ,i , '  :   ' ,D ) ;
                       E := R  ;
                        W r i t e l n('R e a l  ( d i r e c t t o  E x t e n d e d)  ' ,i , '  :   ' ,E ) ;
                       end   ;
                    C l o s e( f) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.256           ReAllocMem

    Synopsis:    Re-allocate memory on the heap

Declaration:     function  ReAllocMem(var  p:  pointer;Size:  PtrInt)  :  pointer

    Visibility:   default

Description:     ReAllocMem resizes the memory pointed to by  P so it has size Size.  The value of  P may
                change  during  this  operation.   The  contents  of  the  memory  pointed  to  by  P  (if  any)  will
                be copied to the new location, but may be truncated if the newly allocated memory block
                is smaller in size.  If a larger block is allocated,  only the used memory is initialized,  extra
                memory will not be zeroed out.

                Note that P may be nil, in that case the behaviour of  ReAllocMem is equivalent to Getmem.

    See also:    GetMem (1251   ), FreeMem (1248   )
                29.9.257           ReAllocMemory

    Synopsis:    Alias for ReAllocMem (1307   )

Declaration:     function  ReAllocMemory(var  p:  pointer;Size:  PtrInt)  :  pointer

    Visibility:   default

Description:     ReAllocMemory is an alias for ReAllocMem (1307   ).

    See also:    ReAllocMem (1307   )

                                                                                1307

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.258           ReleaseExceptionObject

    Synopsis:    Decrease the reference count of the current exception object.

Declaration:     procedure  ReleaseExceptionObject

    Visibility:   default

Description:     ReleaseExceptionObject  decreases  the  reference  count  of  the  current  exception  object.
                This  should  be  called  whenever  a  reference  to  the  exception  object  was  obtained  via  the
                AcquireExceptionObject (1212   ) call.

                Calling this method is only valid within an except block.

       Errors:   If there is no current exception object, a run-time error 231 will occur.

    See also:    AcquireExceptionObject (1212   )
                29.9.259           Rename

    Synopsis:    Rename file on disk

Declaration:     procedure  Rename(var  f:  File;const  s:  String)
                procedure  Rename(var  f:  File;p:  PChar)
                procedure  Rename(var  f:  File;c:  Char)
                procedure  Rename(var  t:  Text;const  s:  String)
                procedure  Rename(var  t:  Text;p:  PChar)
                procedure  Rename(var  t:  Text;c:  Char)

    Visibility:   default

Description:     Rename changes the name of the assigned file F to S. F must be assigned, but not opened.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Erase (1239   )


                Listing:  ./refex/ex77.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 7;


                {   Program       t o  d e m o n s t r a t et h e  Rename      f u n c t i o n.  }
                Var    F   :  T e x t ;


                 b e g i n
                    A s s i g n ( F ,p a r a m s t r( 1 ) ) ;
                    Rename      ( F ,p a r a m s t r( 2 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.260           Reset

    Synopsis:    Open file for reading

Declaration:     procedure  Reset(var  f:  File;l:  LongInt)
                procedure  Reset(var  f:  File)
                procedure  Reset(var  f:  TypedFile)
                procedure  Reset(var  t:  Text)



                                                                                1308

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     Reset  opens  a  file  F  for  reading.   F  can  be  any  file  type.   If  F  is  a  text  file,  or  refers  to
                standard I/O (e.g :  ")  then it is opened read-only,  otherwise it is opened using the mode
                specified in filemode.  If F is an untyped file, the record size can be specified in the optional
                parameter  L.  A  default  value  of  128  is  used.  File  sharing  is  not  taken  into  account  when
                calling Reset.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Rewrite (1310   ), Assign (1216   ), Close (1223   ), Append (1214   )


                Listing:  ./refex/ex51.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 1;


                {   Program       t o  d e m o n s t r a t et h e  R e s e t  f u n c t i o n. }


                 F u n c t i o nF i l e E x i s t s( Name     :  S t r i n g)  :   b o o l e a n;


                Var    F   :   F i l e;


                 b e g i n
                    { $ i- }
                    A s s i g n ( F ,Name    ) ;
                    R e s e t ( F ) ;
                    { $ I+ }
                    F i l e E x i s t:s= ( I o R e s u l t=0)  and    ( Name   <>  ' ') ;
                    C l o s e ( f ) ;
                end   ;


                 b e g i n
                    I f  F i l e E x i s t s( Paramstr      ( 1 ) )  then
                        W r i t e l n(  'F i l e  f o u n d')
                    e l s e
                        W r i t e l n(  'F i l e NOT     f o u n d') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.261           ResumeThread

    Synopsis:    Resume a suspended thread.

Declaration:     function  ResumeThread(threadHandle:  TThreadID)  :  DWord

    Visibility:   default

Description:     ResumeThread  causes  a  suspended  thread  (using  SuspendThread  (1328   ))  to  resume  it's
                execution.  The thread is identified with it's handle or ID threadHandle.

                The function returns zero if succesful.  A nonzero return value indicates failure.

       Errors:   If a failure occurred, a nonzero result is returned.  The meaning is system dependent.

    See also:    SuspendThread (1328   ), KillThread (1266   )

                                                                                1309

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.262           Rewrite

    Synopsis:    Open file for writing

Declaration:     procedure  Rewrite(var  f:  File;l:  LongInt)
                procedure  Rewrite(var  f:  File)
                procedure  Rewrite(var  f:  TypedFile)
                procedure  Rewrite(var  t:  Text)

    Visibility:   default

Description:     Rewrite  opens  a  file  F  for  writing.   F  can  be  any  file  type.   If  F  is  an  untyped  or  typed
                file,  then it is opened for reading and writing.  If  F is an untyped file,  the record size can
                be  specified  in  the  optional  parameter  L.  Default  a  value  of  128  is  used.  if  Rewrite  finds
                a file with the same name as F, this file is truncated to length 0.  If it doesn't find such a
                file, a new file is created.  Contrary to Turbo Pascal, Free Pascal opens the file with mode
                fmoutput.  If it should be opened in fminout mode, an extra call to Reset (1308   ) is needed.
                File sharing is not taken into account when calling Rewrite.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Reset (1308   ), Assign (1216   ), Close (1223   ), Flush (1247   ), Append (1214   )


                Listing:  ./refex/ex52.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 2;


                {   Program       t o  d e m o n s t r a t et h e  R e w r i t e f u n c t i o n. }


                Var    F   :   F i l e;
                        I  :   l o n g i n t;


                 b e g i n
                    A s s i g n ( F , 'T e s t. tmp  ' ) ;
                    {   C r e a t e t h e  f i l e.  R e c o r d s i z e i s 4   }
                    R e w r i t e (F  ,S i z e o f( I) ) ;
                    For    I : = 1  t o  1 0  do
                       B l o c k W r i t e (F , I , 1 ) ;
                    c l o s e ( f ) ;
                    {  F   c o n t a i n snow     a  b i n a r y  r e p r e s e n t a t i o no f
                        1 0  l o n g i n t sg o i n g  f r o m 1   t o  1 0  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.263           rmdir

    Synopsis:    Remove directory when empty.

Declaration:     procedure  rmdir(const  s:  String)

    Visibility:   default

Description:     Rmdir removes the directory S.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Chdir (1222   ), Mkdir (1271   )



                                                                                1310

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                Listing:  ./refex/ex53.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 3;


                {   Program       t o  d e m o n s t r a t et h e  MkDir     and    RmDir      f u n c t i o n s. }


                Const      D   :  S t r i n g[ 8 ]  =  'TEST    .DIR   ';


                Var    S   :   S t r i n g;


                 b e g i n
                    W r i t e l n ( 'Making       d i r e c t o r y' ,D  ) ;
                    Mkdir     ( D ) ;
                    W r i t e l n ( 'C h a n g i n g d i r e c t o r y t o  ' ,D ) ;
                    ChDir     ( D ) ;
                    G e t D i r ( 0 ,S ) ;
                    W r i t e l n ( ' C u r r e n t D i r e c t o r yi s  :   ' ,S ) ;
                    WRiteln       ( 'G o i n g  b a c k' ) ;
                    ChDir     (  '. . ') ;
                    W r i t e l n ( 'Removing        d i r e c t o r y ' ,D ) ;
                    RmDir     ( D ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.264           round

    Synopsis:    Round floating point value to nearest integer number.

Declaration:     function  round(d:  ValReal)  :  Int64

    Visibility:   default

Description:     Round rounds X to the closest integer, which may be bigger or smaller than X.

                In  the  case  of  .5,  the  algorithm  uses  b nker's  rounding":  .5  values  are  always  rounded
                towards the even number.

       Errors:   None.

    See also:    Frac (1248   ), Int (1262   ), Trunc (1333   )


                Listing:  ./refex/ex54.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 4;


                {   Program       t o  d e m o n s t r a t et h e  Round      f u n c t i o n. }


                 b e g i n
                    W r i t e l n (Round     ( 1 2 3 4 . 5 6 ) ) ; {   P r i n t s1 2 3 5         }
                    W r i t e l n (Round     ( - 1 2 3 4 . 5 6 ) ) ;{  P r i n t s-1235           }
                    W r i t e l n (Round     ( 1 2 . 3 4 5 6 ) ) ; {   P r i n t s 1 2            }
                    W r i t e l n (Round     ( - 1 2 . 3 4 5 6 ) ) ;{  P r i n t s-12             }
                    W r i t e l n (Round     ( 2 . 5 ) ) ;         {   P r i n t s 2  ( down   )  }
                    W r i t e l n (Round     ( 3 . 5 ) ) ;         {   P r i n t s 4  ( up  )     }


                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1311

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.265           RTLEventCreate

    Synopsis:    Create a new RTL event

Declaration:     function  RTLEventCreate  :  PRTLEvent

    Visibility:   default

Description:     RTLEventCreate creates and initializes a new RTL event.  RTL events are used to notify
                other threads that a certain condition is met, and to notify other threads of condition changes
                (conditional variables).

                The function returns an initialized RTL event, which must be disposed of with RTLEvent-
                destroy (1312   )

                RTLEvent is used mainly for the synchronize method.

    See also:    RTLEventDestroy (1312   ), RTLEventSet (1165   ), RTLEventReSet (1165   ), RTLEventWaitFor
                (1313   )
                29.9.266           RTLeventdestroy

    Synopsis:    Destroy a RTL Event

Declaration:     procedure  RTLeventdestroy(state:  PRTLEvent)

    Visibility:   default

Description:     RTLeventdestroy  destroys  the  RTL  event  State.  After  a  call  to  RTLeventdestroy,  the
                State RTL event may no longer be used.

    See also:    RTLEventCreate (1312   ), RTLEventReset (1165   ), RTLEventSet (1165   )
                29.9.267           RTLeventResetEvent

    Synopsis:    Reset an event

Declaration:     procedure  RTLeventResetEvent(state:  PRTLEvent)

    Visibility:   default

Description:     RTLeventResetEvent resets the event:  this should be used to undo the signaled state of an
                event.  Resetting an event that is not set (or was already reset) has no effect.

    See also:    RTLEventCreate (1312   ), RTLEventDestroy (1312   ), RTLEventSetEvent (1312   ), RTLEvent-
                WaitFor (1313   )
                29.9.268           RTLeventSetEvent

    Synopsis:    Notify threads of the event.

Declaration:     procedure  RTLeventSetEvent(state:  PRTLEvent)

    Visibility:   default

Description:     RTLeventSetEvent notifies other threads which are listening, that the event has occurred.

    See also:    RTLEventCreate (1312   ), RTLEventResetEvent (1312   ), RTLEventDestroy (1312   ), RTLEvent-
                WaitFor (1313   )
                                                                                1312

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.269           RTLeventsync

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  RTLeventsync(m:  trtlmethod;p:  TProcedure)

    Visibility:   default

Description:     RTLeventsync is obsolete, don't use it.
                29.9.270           RTLeventWaitFor

    Synopsis:    Wait for an event.

Declaration:     procedure  RTLeventWaitFor(state:  PRTLEvent)
                procedure  RTLeventWaitFor(state:  PRTLEvent;timeout:  LongInt)

    Visibility:   default

Description:     RTLeventWaitFor  suspends  the  thread  till  the  event  occurs.   The  event  will  occur  when
                another thread calls RTLEventSetEvent (1312   ) on State.

                By default, the thread will be suspended indefinitely.  However, if TimeOut is specified, then
                the thread will resume after timeout milliseconds have elapsed.

    See also:    RTLEventCreate (1312   ), RTLEventDestroy (1312   ), RTLEventSetEvent (1312   ), RTLEvent-
                WaitFor (1313   )
                29.9.271           RunError

    Synopsis:    Generate a run-time error.

Declaration:     procedure  RunError(w:  Word)
                procedure  RunError

    Visibility:   default

Description:     Runerror stops the execution of the program, and generates a run-time error ErrorCode.

       Errors:   None.

    See also:    Exit (1241   ), Halt (1253   )


                Listing:  ./refex/ex55.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 5;


                {   Program       t o  d e m o n s t r a t et h e  R u n E r r o r f u n c t i o n. }


                 b e g i n
                    {  The    p r o g r a m  w i l l s t o p  end    e m i t a   run  - e r r o r 1 0 6  }
                    R u n E r r o r ( 1 0 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                1313

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.272           Seek

    Synopsis:    Set file position

Declaration:     procedure  Seek(var  f:  File;Pos:  Int64)

    Visibility:   default

Description:     Seek sets the file-pointer for file F to record Nr.  Count.  The first record in a file has Count=0.
                F can be any file type, except Text.  If  F is an untyped file, with no record size specified in
                Reset (1308   ) or Rewrite (1310   ), 128 is assumed.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Eof (1237   ), SeekEof (1314   ), SeekEoln (1315   )


                Listing:  ./refex/ex56.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 6;


                {   Program       t o  d e m o n s t r a t et h e  S e e k  f u n c t i o n. }


                Var
                    F   :  F i l e;
                    I , j  :   l o n g i n t;


                 b e g i n
                    {   C r e a t e a   f i l e and    f i l l  i t  w i t h  d a t a }
                    A s s i g n ( F , 't e s t. tmp  ' ) ;
                    R e w r i t e(F ) ;  {   C r e a t e f i l e }
                    C l o s e( f) ;
                    F i l e M o d e: = 2 ;
                    ReSet     ( F , S i z e o f(i ) ) ; {   Opened      r e a d/ w r i t e }
                    For    I : = 0  t o  1 0  do
                       B l o c k W r i t e (F , I , 1 ) ;
                    {  Go    Back    t o   t h e  b e g i n i n go f   t h e  f i l e }
                    Seek   (F  , 0 ) ;
                    For    I : = 0  t o  1 0  do
                        b e g i n
                       BlockRead         (F  ,J , 1 ) ;
                        I f  J<>  I  then
                           W r i t e l n ( ' E r r o r:  e x p e c t e d '  , i, ' ,  g o t   ', j ) ;
                       end   ;
                    C l o s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.273           SeekEOF

    Synopsis:    Set file position to end of file

Declaration:     function  SeekEOF(var  t:  Text)  :  Boolean
                function  SeekEOF  :  Boolean

    Visibility:   default

Description:     SeekEof returns True is the file-pointer is at the end of the file.  It ignores all whitespace.
                Calling  this  function  has  the  effect  that  the  file-position  is  advanced  until  the  first  non-
                whitespace character or the end-of-file marker is reached.



                                                                                1314

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                If the end-of-file marker is reached, True is returned.  Otherwise, False is returned.

                If the parameter F is omitted, standard Input is assumed.

 Remark:         The SeekEOF function can only be used on real textfiles:  when assigning the file to other
                kinds of (virtual) text files, the function may fail, although it will perform a number of tests
                to guard against wrong usage.

       Errors:   A run-time error is generated if the file F isn't opened.

    See also:    Eof (1237   ), SeekEoln (1315   ), Seek (1314   )


                Listing:  ./refex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 7;


                {   Program       t o  d e m o n s t r a t et h e  S e e k E o f f u n c t i o n. }
                Var    C   :  Char    ;


                 b e g i n
                    {   t h i s  w i l l p r i n t  a l l  c h a r a c t e r sf r o m s t a n d a r d i n p u t e x c e p t
                        W h i t e s p a c ec h a r a c t e r.s }
                    While     Not    SeekEof       do
                        b e g i n
                       Read     ( C ) ;
                       Write      (C  ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.274           SeekEOLn

    Synopsis:    Set file position to end of line

Declaration:     function  SeekEOLn(var  t:  Text)  :  Boolean
                function  SeekEOLn  :  Boolean

    Visibility:   default

Description:     SeekEoln  returns  True  is  the  file-pointer  is  at  the  end  of  the  current  line.  It  ignores  all
                whitespace.  Calling this function has the effect that the file-position is advanced until the
                first non-whitespace character or the end-of-line marker is reached.  If the end-of-line marker
                is reached, True is returned.  Otherwise, False is returned.  The end-of-line marker is defined
                as #10, the LineFeed character.  If the parameter F is omitted, standard Input is assumed.

       Errors:   A run-time error is generated if the file F isn't opened.

    See also:    Eof (1237   ), SeekEof (1314   ), Seek (1314   )


                Listing:  ./refex/ex58.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 8;


                {   Program       t o  d e m o n s t r a t et h e  S e e k E o l n f u n c t i o n. }
                Var
                    C   :  Char   ;


                 b e g i n
                    {   T h i s  w i l l r e a d  t h e  f i r s t l i n e  o f  s t a n d a r d o u t p u t and    p r i n t
                        a l l  c h a r a c t e r se x c e p t w h i t e s p a c e. }



                                                                                1315

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    While     not    SeekEoln        do
                       Begin
                       Read     ( c ) ;
                       Write      ( c ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.275           Seg

    Synopsis:    Return segment

Declaration:     function  Seg(var  X)  :  LongInt

    Visibility:   default

Description:     Seg returns the segment of the address of a variable.  This function is only supported for
                compatibility.  In  Free  Pascal,  it  returns  always  0,  since  Free  Pascal  uses  a  flat  32/64  bit
                memory model.  In such a memory model segments have no meaning.

       Errors:   None.

    See also:    DSeg (1235   ), CSeg (1231   ), Ofs (1275   ), Ptr (1302   )


                Listing:  ./refex/ex60.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 0;


                {   Program       t o  d e m o n s t r a t et h e  Seg    f u n c t i o n. }
                Var
                   W    :  Word   ;


                 b e g i n
                   W  := Seg  (W  ) ;    {  W   c o n t a i n s i t s own    Segment      }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.276           Setjmp

    Synopsis:    Save current execution point.

Declaration:     function  Setjmp(var  S:  jmp_buf)  :  LongInt

    Visibility:   default

Description:     SetJmp fills env with the necessary data for a jump back to the point where it was called.
                It returns zero if called in this way.  If the function returns nonzero,  then it means that a
                call to LongJmp (1270   ) with env as an argument was made somewhere in the program.

       Errors:   None.

    See also:    LongJmp (1270   )


                Listing:  ./refex/ex79.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 7 9;


                {   Program       t o  d e m o n s t r a t et h e  s e t j m p,  l o n g j m p f u n c t i o n s}
                                                                                1316

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                 p r o c e d u r edojmp    (v a r  e n v   :  j m p _b u f;   v a l u e :   l o n g i n t) ;


                 b e g i n
                    v a l u e: = 2 ;
                    W r i t e l n ( 'G o i n g  t o  jump     ! ' ) ;
                    {   T h i s  w i l l r e t u r n t o  t h e  s e t j m p  c a l l,
                       and     r e t u r n v a l u e i n s t e a d o f  0   }
                    l o n g j m p(env  , v a l u e) ;
                end   ;


                 v a r e n v   :  j m p _b u f;


                 b e g i n
                    i f  s e t j m p(e n v )=0    then
                        b e g i n
                        w r i t e l n(  'P a s s e d  f i r s t t i m e. ') ;
                       dojmp    ( env  , 2 ) ;
                       end
                    e l s e
                        w r i t e l n(  'P a s s e d s e c o n d t i m e. ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.277           SetLength

    Synopsis:    Set length of a string.

Declaration:     procedure  SetLength(var  S:  AStringType;Len:  Integer)
                procedure  SetLength(var  A:  DynArrayType;Len:  Integer)

    Visibility:   default

Description:     SetLength sets the length of the string S to Len.  S can be an ansistring, a short string or
                a widestring.  For ShortStrings, Len can maximally be 255.  For AnsiStrings it can have
                any value.  For AnsiString strings, SetLength {\em must} be used to set the length of the
                string.

                In the case of a dynamical array A, setlength sets the number of elements.  The elements are
                numbered from index 0, so the count runs from 0 to Len-1.  If Zero is specified, the array is
                cleared.

       Errors:   None.

    See also:    Length (1267   )


                Listing:  ./refex/ex85.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 5;


                {   Program       t o  d e m o n s t r a t et h e  S e t L e n g t h f u n c t i o n. }


                Var    S   :   S t r i n g;


                 b e g i n
                    F i l l C h a r(S [ 1 ] , 1 0 0 , # 3 2 ) ;
                    S e t l e n g t h(S, 1 0 0 ) ;
                    W r i t e l n ( '"  ',S  , '" ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1317

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.278           SetMemoryManager

    Synopsis:    Set a memory manager

Declaration:     procedure  SetMemoryManager(const  MemMgr:  TMemoryManager)

    Visibility:   default

Description:     SetMemoryManager sets the current memory manager record to MemMgr.

                For an example, see \progref.

       Errors:   None.

    See also:    GetMemoryManager (1251   ), IsMemoryManagerSet (1266   )
                29.9.279           SetMemoryMutexManager

    Synopsis:    Procedure to set the mutex manager.

Declaration:     procedure  SetMemoryMutexManager(var  MutexMgr:  TMemoryMutexManager)

    Visibility:   default

Description:     SetMemoryMutexManager sets the mutex manager used by the memory manager to MutexMgr.
                The current mutex manager is returned in MutexMgr

       Errors:   None.

    See also:    TMemoryMutexManager (1201   ), SetMemoryManager (1318   )
                29.9.280           SetString

    Synopsis:    Set length of a string and copy buffer.

Declaration:     procedure  SetString(out  S:  AnsiString;Buf:  PChar;Len:  SizeInt)
                procedure  SetString(out  S:  Shortstring;Buf:  PChar;Len:  SizeInt)
                procedure  SetString(out  S:  WideString;Buf:  PWideChar;Len:  SizeInt)
                procedure  SetString(out  S:  WideString;Buf:  PChar;Len:  SizeInt)

    Visibility:   default

Description:     SetString sets the length of the string S to Len and if Buf is non-nil, copies Len characters
                from Buf into S. S can be an ansistring, a short string or a widestring.  For ShortStrings,
                Len can maximally be 255.

       Errors:   None.

    See also:    SetLength (1317   )
                29.9.281           SetTextBuf

    Synopsis:    Set size of text file internal buffer

Declaration:     procedure  SetTextBuf(var  f:  Text;var  Buf)
                procedure  SetTextBuf(var  f:  Text;var  Buf;Size:  SizeInt)

    Visibility:   default

                                                                                1318

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     SetTextBuf assigns an I/O buffer to a text file.  The new buffer is located at Buf and is
                Size  bytes  long.  If  Size  is  omitted,  then  SizeOf(Buf)  is  assumed.  The  standard  buffer
                of any text file is 128 bytes long.  For heavy I/O operations this may prove too slow.  The
                SetTextBuf  procedure  allows  to  set  a  bigger  buffer  for  the  I/O  of  the  application,  thus
                reducing the number of system calls,  and thus reducing the load on the system resources.
                The maximum size of the newly assigned buffer is 65355 bytes.

 Remark:

                      oNever assign a new buffer to an opened file.  A new buffer can be assigned immediately
                      after a call to Rewrite (1310   ), Reset (1308   ) or Append, but not after the file was read
                      from/written to.  This may cause loss of data.  If a new buffer must be assigned after
                      read/write operations have been performed, the file should be flushed first.  This will
                      ensure that the current buffer is emptied.

                      oTake care that the assigned buffer is always valid.  If a local variable is assigned as a
                      buffer, then after the program exits the local program block, the buffer will no longer
                      be valid, and stack problems may occur.

       Errors:   No checking on Size is done.

    See also:    Assign (1216   ), Reset (1308   ), Rewrite (1310   ), Append (1214   )


                Listing:  ./refex/ex61.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 1;


                {   Program       t o  d e m o n s t r a t et h e  S e t T e x t B u ff u n c t i o n.  }


                Var
                    F i n, F o u t  :  T e x t;
                    Ch   :   Char   ;
                    B u f i n,B u f o u t  :  A r r a y[ 1 . . 1 0 0 0 0 ]o f  b y t e;


                 b e g i n
                    A s s i g n ( F i n, p a r a m s t r( 1 ) ) ;
                    R e s e t ( F i n ) ;
                    A s s i g n ( Fout   , p a r a m s t r( 2 ) ) ;
                    R e w r i t e ( F o u t) ;
                    {   T h i s i s   h a r m l e s sb e f o r e IO    h a s begun      }
                    {  Try     t h i s p r o g r a m a g a i n on    a  b i g   f i l e,
                        a f t e r commenting         o u t  t h e  f o l l o w i n g2
                        l i n e s and    r e c o m p i l i n gi t .  }
                    SetTextBuf         ( F i n, B u f i n) ;
                    SetTextBuf         ( Fout   , B u f o u t) ;
                    While     not    e o f (F i n )  do
                        b e g i n
                       Read     ( F i n, ch  ) ;
                        w r i t e ( Fout   ,ch  ) ;
                       end   ;
                    C l o s e ( F i n ) ;
                    C l o s e ( F o u t) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.282           SetTextLineEnding

    Synopsis:    Set the end-of-line character for the given text file.
                                                                                1319

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Declaration:     procedure  SetTextLineEnding(var  f:  Text;Ending:  String)

    Visibility:  default

Description:     SetTextLineEnding sets the end-of-line character for the text file F to Ending.  By default,
                this is the string indicated by DefaultTextLineBreakStyle (1170   ).

       Errors:   None.

    See also:    DefaultTextLineBreakStyle (1170   ), TTextLineBreakStyle (1203   )
                29.9.283           SetThreadManager

    Synopsis:    Set the thread manager, optionally return the current thread manager.

Declaration:     function  SetThreadManager(const  NewTM:  TThreadManager;
                                                         var  OldTM:  TThreadManager)  :  Boolean
                function  SetThreadManager(const  NewTM:  TThreadManager)  :  Boolean

    Visibility:   default

Description:     SetThreadManager sets the thread manager to NewTM. If OldTM is given, SetThreadManager
                uses it to return the previously used thread manager.

                The  function  returns  True  if  the  threadmanager  was  set  succesfully,  False  if  an  error  oc-
                curred.

                For more information about thread programming, see the programmer's guide.

       Errors:   If an error occurred cleaning up the previous manager, or an error occurred initializing the
                new manager, False is returned.

    See also:    GetThreadManager (1252   ), TThreadManager (1205   )
                29.9.284           SetVariantManager

    Synopsis:    Set the current variant manager.

Declaration:     procedure  SetVariantManager(const  VarMgr:  tvariantmanager)

    Visibility:   default

Description:     SetVariantManager sets the variant manager to varmgr.

    See also:    IsVariantManagerSet (1165   ), GetVariantManager (1252   )
                29.9.285           SetWideStringManager

    Synopsis:    Set the widestring manager

Declaration:     procedure  SetWideStringManager(const  New:  TWideStringManager)
                procedure  SetWideStringManager(const  New:  TWideStringManager;
                                                                  var  Old:  TWideStringManager)

    Visibility:   default


                                                                                1320

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     SetWideStringManager sets the current widestring manager to New.  Optionally, it returns
                the currently active widestring manager in Old.

                WideStrings are implemented in different ways on different platforms.  Therefore, the Free
                Pascal Runtime library has no fixed implementation of widestring routines.  Instead, it defines
                a WideString manager record,  with callbacks that can be set to an implementation which
                is most efficient on the current platform.  On windows, standard Windows routines will be
                used.  On Unix and Linux,  an implementation based on the C library is available (in unit
                cwstrings).

                It is possible to implement a custom widestring manager, optimized for the current applica-
                tion, without having to recompile the complete Run-Time Library.

       Errors:

    See also:    TWideStringManager (1208   )
                29.9.286           ShortCompareText

    Synopsis:    Compare 2 shortstrings

Declaration:     function  ShortCompareText(const  S1:  shortstring;const  S2:  shortstring)
                                                           :  SizeInt

    Visibility:   default

Description:     ShortCompareText compares two shortstrings, S1 and S2, and returns the following result:


                <0 if  S1<S2.

                0 if  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:    #rtl.sysutils.CompareText (1398   )
                29.9.287           sin

    Synopsis:    Calculate sine of angle

Declaration:     function  sin(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Sin returns the sine of its argument X, where X is an angle in radians.  If the absolute value
                of the argument is larger than 2^63, then the result is undefined.

       Errors:   None.

    See also:    Cos (1231   ), Pi (1300   ), Exp (1242   ), Ln (1268   )


                Listing:  ./refex/ex62.pp
                                                                                1321

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   Program       t o  d e m o n s t r a t et h e  S i n  f u n c t i o n. }


                 b e g i n
                    W r i t e l n ( S i n( P i) : 0 : 1 ) ;    {   P r i n t s 0 . 0  }
                    W r i t e l n ( S i n( P i/ 2 ) : 0 : 1 ) ;{   P r i n t s 1 . 0  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.288           SizeOf

    Synopsis:    Return size of a variable or type.

Declaration:     function  SizeOf(X:  TAnyType)  :  LongInt

    Visibility:   default

Description:     SizeOf returns the size, in bytes, of any variable or type-identifier.

 Remark:         This isn't really a RTL function.  Its result is calculated at compile-time, and hard-coded in
                the executable.

       Errors:   None.

    See also:    Addr (1213   )


                Listing:  ./refex/ex63.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 3;


                {   Program       t o  d e m o n s t r a t et h e  S i z e O f f u n c t i o n.  }
                Var
                    I   :  L o n g i n t;
                    S   :  S t r i n g [ 1 0 ] ;


                 b e g i n
                    W r i t e l n ( S i z e O f(I ) ) ;   {   P r i n t s 4    }
                    W r i t e l n ( S i z e O f(S ) ) ;   {   P r i n t s 1 1  }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.289           SizeofResource

    Synopsis:    Return the size of a particular resource

Declaration:     function  SizeofResource(ModuleHandle:  HMODULE;
                                                      ResHandle:  TResourceHandle)  :  Integer

    Visibility:   default

Description:     SizeOfResource returns the size of the resource identified by ResHandle in module identi-
                fied by ModuleHandle.  ResHandle should be obtained from a call to LoadResource (1269   )

       Errors:   In case of an error, 0 is returned.

    See also:    FindResource (1246   ), FreeResource (1249   ), LoadResource (1269   ), LockResource (1269   ), Un-
                lockResource (1335   ), FreeResource (1249   )
                                                                                1322

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.290           Space

    Synopsis:    Return a string of spaces

Declaration:     function  Space(b:  Byte)  :  shortstring

    Visibility:   default

Description:     Space returns a shortstring with length B, consisting of spaces.

    See also:    StringOfChar (1325   )
                29.9.291           Sptr

    Synopsis:    Return current stack pointer

Declaration:     function  Sptr  :  Pointer

    Visibility:   default

Description:     Sptr returns the current stack pointer.

       Errors:   None.

    See also:    SSeg (1324   )


                Listing:  ./refex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 6 4;


                {   Program       t o  d e m o n s t r a t et h e  s p t r  f u n c t i o n. }


                 v a r p : p t r u i n t;


                 b e g i n
                    p := o f s( s p t r) ;  {   P  C o n t a i n s now    t h e  c u r r e n t s t a c k  p o s i t i o n. }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.292           sqr

    Synopsis:    Calculate the square of a value.

Declaration:     function  sqr(l:  LongInt)  :  LongInt
                function  sqr(l:  Int64)  :  Int64
                function  sqr(l:  QWord)  :  QWord
                function  sqr(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Sqr returns the square of its argument X.

       Errors:   None.

    See also:    Sqrt (1324   ), Ln (1268   ), Exp (1242   )


                Listing:  ./refex/ex65.pp



                                                                                1323

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 5;


                {   Program       t o  d e m o n s t r a t et h e  S q r  f u n c t i o n. }
                Var     i  :   I n t e g e r;


                 b e g i n
                    For    i : = 1  t o  1 0  do
                        w r i t e l n( Sqr  ( i ) : 3 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.293           sqrt

    Synopsis:    Calculate the square root of a value

Declaration:     function  sqrt(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Sqrt returns the square root of its argument X, which must be positive.

       Errors:   If  X is negative, then a run-time error is generated.

    See also:    Sqr (1323   ), Ln (1268   ), Exp (1242   )


                Listing:  ./refex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   Program       t o  d e m o n s t r a t et h e  S q r t  f u n c t i o n. }


                 b e g i n
                    W r i t e l n ( S q r t( 4 ) : 0 : 3 ) ;{   P r i n t s 2 . 0 0 0 }
                    W r i t e l n ( S q r t( 2 ) : 0 : 3 ) ;{   P r i n t s 1 . 4 1 4 }
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.294           Sseg

    Synopsis:    Return stack segment register value.

Declaration:     function  Sseg  :  Word

    Visibility:   default

Description:     SSeg returns the Stack Segment.  This function is only supported for compatibility reasons,
                as Sptr returns the correct contents of the stackpointer.

       Errors:   None.

    See also:    Sptr (1323   )


                Listing:  ./refex/ex67.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                {   Program       t o  d e m o n s t r a t et h e  SSeg     f u n c t i o n. }
                Var    W   :   L o n g i n t;



                                                                                1324

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________


                 b e g i n
                   W  := SSeg   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.295           Str

    Synopsis:    Convert a numerical value to a string.

Declaration:     procedure  Str(var  X:  TNumericType;var  S:  String)

    Visibility:   default

Description:     Str  returns  a  string  which  represents  the  value  of  X.  X  can  be  any  numerical  type.  The
                actual declaration of  Str is not according to pascal syntax, and should be


                procedure  Str(var  X:  TNumericType[:NumPlaces[:Decimals]];var  S:  String)


                Where the optional NumPlaces and Decimals specifiers control the formatting of the string:
                NumPlaces gives the total width of the string, and Decimals the number of decimals after
                the decimal separator char.

       Errors:   None.

    See also:    Val (1337   )


                Listing:  ./refex/ex68.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 8;


                {   Program       t o  d e m o n s t r a t et h e  S t r  f u n c t i o n. }
                Var    S   :   S t r i n g;


                 F u n c t i o nI n t T o S t r ( I  :   L o n g i n t)  :  S t r i n g;


                Var    S   :   S t r i n g;


                 b e g i n
                  S t r  ( I ,S ) ;
                  I n t T o S t r:=S  ;
                end   ;


                 b e g i n
                    S :=  '* '+ I n t T o S t r(-233)+     '* ' ;
                    W r i t e l n (S  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.296           StringOfChar

    Synopsis:    Return a string consisting of 1 character repeated N times.

Declaration:     function  StringOfChar(c:  Char;l:  SizeInt)  :  AnsiString

    Visibility:   default

                                                                                1325

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     StringOfChar creates a new String of length l and fills it with the character c.

                It is equivalent to the following calls:


                SetLength(StringOfChar,l);
                FillChar(Pointer(StringOfChar)^,Length(StringOfChar),c);


       Errors:   None.

    See also:    SetLength (1317   )


                Listing:  ./refex/ex97.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 7;


                { $H + }


                {   Program       t o  d e m o n s t r a t et h e  S t r i n g O f C h a rf u n c t i o n. }


                Var    S   :   S t r i n g;


                 b e g i n
                    S := S t r i n g O f C h a(r'   ',40)+    ' A l i g n e d a t  column      4 1 . ';
                    W r i t e l n(s ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.297           StringToPPChar

    Synopsis:    Split string in list of null-terminated strings

Declaration:     function  StringToPPChar(var  S:  AnsiString;ReserveEntries:  Integer)
                                                        :  PPChar
                function  StringToPPChar(S:  PChar;ReserveEntries:  Integer)  :  PPChar

    Visibility:   default

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.

                The function reserves memory on the heap to store the array of PChar; The caller is respon-
                sible for freeing this memory.

                This function is only available on certain platforms.

       Errors:   None.

    See also:    ArrayStringToPPchar (1215   )
                29.9.298           StringToWideChar

    Synopsis:    Convert a string to an array of widechars.

Declaration:     function  StringToWideChar(const  Src:  AnsiString;Dest:  PWideChar;
                                                         DestSize:  SizeInt)  :  PWideChar



                                                                                1326

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
    Visibility:  default

Description:     StringToWideChar converts an ansistring Src to a null-terminated array of WideChars.  The
                destination  for  this  array  is  pointed  to  by  Dest,  and  contains  room  for  at  least  DestSize
                widechars.

       Errors:   No validity checking is performed on Dest.

    See also:    WideCharToString (1339   ), WideCharToStrVar (1340   ), WideCharLenToStrVar (1339   ), WideCharLen-
                ToString (1339   )
                29.9.299           strlen

    Synopsis:    Length of a null-terminated string.

Declaration:     function  strlen(p:  PChar)  :  LongInt

    Visibility:   default

Description:     Returns the length of the null-terminated string P.

       Errors:   None.
                29.9.300           strpas

    Synopsis:    Convert a null-terminated string to a shortstring.

Declaration:     function  strpas(p:  PChar)  :  shortstring

    Visibility:   default

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.
                29.9.301           Succ

    Synopsis:    Return next element of ordinal type.

Declaration:     function  Succ(X:  TOrdinal)  :  TOrdinal

    Visibility:   default

Description:     Succ returns the element that succeeds the element that was passed to it.  If it is applied
                to the last value of the ordinal type, and the program was compiled with range checking on
                (\var{\{\$R+\}}), then a run-time error will be generated.

                for an example, see Ord (1299   ).

       Errors:   Run-time error 201 is generated when the result is out of range.

    See also:    Ord (1299   ), Pred (1302   ), High (1255   ), Low (1270   )

                                                                                1327

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.302           SuspendThread

    Synopsis:    Suspend a running thread.

Declaration:     function  SuspendThread(threadHandle:  TThreadID)  :  DWord

    Visibility:   default

Description:     SuspendThread suspends a running thread.  The thread is identified with it's handle or ID
                threadHandle.

                The function returns zero if succesful.  A nonzero return value indicates failure.

       Errors:   If a failure occurred, a nonzero result is returned.  The meaning is system dependent.

    See also:    ResumeThread (1309   ), KillThread (1266   )
                29.9.303           Swap

    Synopsis:    Swap high and low bytes/words of a variable

Declaration:     function  swap(X:  Word)  :  Word
                function  Swap(X:  Integer)  :  Integer
                function  swap(X:  LongInt)  :  LongInt
                function  Swap(X:  Cardinal)  :  Cardinal
                function  Swap(X:  QWord)  :  QWord
                function  swap(X:  Int64)  :  Int64

    Visibility:   default

Description:     Swap swaps the high and low order bytes of X if X is of type Word or Integer, or swaps the
                high and low order words of  X if  X is of type Longint or Cardinal.  The return type is the
                type of  X

       Errors:   None.

    See also:    Lo (1268   ), Hi (1254   )


                Listing:  ./refex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   Program       t o  d e m o n s t r a t et h e  Swap     f u n c t i o n. }
                Var    W   :  Word    ;
                       L   :   L o n g i n t;


                 b e g i n
                   W  := $1234    ;
                   W  := Swap   (W  ) ;
                    i f  W<>  $3412      then
                        w r i t e l n(  'E r r o r when     s w a p p i n g word     ! ') ;
                    L := $ 1 2 3 4 5 6 7 8;
                    L := Swap   ( L ) ;
                    i f  L<>  $ 5 6 7 8 1 2 3 4 then
                        w r i t e l n(  'E r r o r when     s w a p p i n g L o n g i n t ! ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1328

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.304           SwapEndian

    Synopsis:    Swap endianness of the argument

Declaration:     function  SwapEndian(const  AValue:  SmallInt)  :  SmallInt
                function  SwapEndian(const  AValue:  Word)  :  Word
                function  SwapEndian(const  AValue:  LongInt)  :  LongInt
                function  SwapEndian(const  AValue:  DWord)  :  DWord
                function  SwapEndian(const  AValue:  Int64)  :  Int64
                function  SwapEndian(const  AValue:  QWord)  :  QWord

    Visibility:   default

Description:     SwapEndian will swap the endianness of the bytes in its argument.

       Errors:   None.

    See also:    hi (1254   ), lo (1268   ), swap (1328   ), BEToN (1219   ), NToBE (1273   ), NToLE (1273   ), LEToN
                (1268   )
                29.9.305           SysAllocMem

    Synopsis:    System memory manager:  Allocate memory

Declaration:     function  SysAllocMem(size:  PtrInt)  :  Pointer

    Visibility:   default

Description:     SysFreemSize is the system memory manager implementation for AllocMem (1214   )

    See also:    AllocMem (1214   )
                29.9.306           SysAssert

    Synopsis:    Standard Assert failure implementation

Declaration:     procedure  SysAssert(const  Msg:  ShortString;const  FName:  ShortString;
                                                LineNo:  LongInt;ErrorAddr:  Pointer)

    Visibility:   default

Description:     SysAssert  is  the  standard  implementation  of  the  assertion  failed  code.  It  is  the  default
                value of the AssertErrorProc constant.  It will print the assert message Msg together with
                the filename FName and linenumber LineNo to standard error output (StdErr) and will halt
                the program with exit code 227.  The error address ErrorAddr is ignored.

    See also:    AssertErrorProc (1169   )
                29.9.307           SysBackTraceStr

    Synopsis:    Format an address suitable for inclusion in a backtrace

Declaration:     function  SysBackTraceStr(Addr:  Pointer)  :  ShortString

    Visibility:   default

Description:     SysBackTraceStr will create a string representation of the address Addr, suitable for inclu-
                sion in a stack backtrace.

       Errors:   None.



                                                                                1329

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.308           SysFreemem

    Synopsis:    System memory manager free routine.

Declaration:     function  SysFreemem(p:  pointer)  :  PtrInt

    Visibility:   default

Description:     SysFreeem is the system memory manager implementation for FreeMem (1248   )

    See also:    FreeMem (1248   )
                29.9.309           SysFreememSize

    Synopsis:    System memory manager free routine.

Declaration:     function  SysFreememSize(p:  pointer;Size:  PtrInt)  :  PtrInt

    Visibility:   default

Description:     SysFreemSize is the system memory manager implementation for FreeMem (1248   )

    See also:    MemSize (1271   )
                29.9.310           SysGetFPCHeapStatus

    Synopsis:    Return the status of the FPC heapmanager

Declaration:     function  SysGetFPCHeapStatus  :  TFPCHeapStatus

    Visibility:   default

Description:     SysGetFPCHeapStatus returns the status of the default FPC heapmanager.  It is set as the
                default value of the corresponding GetFPCHeapStatus (1250   ) function.

       Errors:   None.  The result of this function is bogus information if the current heapmanager is not
                the standard FPC heapmanager.

    See also:    GetFPCHeapStatus (1250   )
                29.9.311           SysGetHeapStatus

    Synopsis:    System implementation of GetHeapStatus (1250   )

Declaration:     function  SysGetHeapStatus  :  THeapStatus

    Visibility:   default

Description:     SysGetHeapStatus is the system implementation of the GetHeapStatus (1250   ) call.

    See also:    GetHeapStatus (1250   )
                29.9.312           SysGetmem

    Synopsis:    System memory manager memory allocator.

Declaration:     function  SysGetmem(Size:  PtrInt)  :  Pointer

    Visibility:   default

Description:     SysGetmem is the system memory manager implementation for GetMem (1251   )

    See also:    GetMem (1251   ), GetMemory (1251   )



                                                                                1330

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.313           SysInitExceptions

    Synopsis:    Initialize exceptions.

Declaration:     procedure  SysInitExceptions

    Visibility:   default

Description:     SysInitExceptions initializes the exception system.  This procedure should never be called
                directly, it is taken care of by the RTL.
                29.9.314           SysInitFPU

    Synopsis:    Initialize the FPU

Declaration:     procedure  SysInitFPU

    Visibility:   default

Description:     SysInitFPU  initializes  (resets)  the  floating  point  unit,  if  one  is  available.  It  is  called  for
                instance when a new thread is started.

    See also:    BeginThread (1218   )
                29.9.315           SysInitStdIO

    Synopsis:    Initialize standard input and output.

Declaration:     procedure  SysInitStdIO

    Visibility:   default

Description:     SysInitStdIO initializes the standard input and output files:  Output (1210   ), Input (1210   )
                and StdErr (1211   ).  This routine is called by the initialization code of the system unit, there
                should be no need to call it directly.
                29.9.316           SysMemSize

    Synopsis:    System memory manager:  free size.

Declaration:     function  SysMemSize(p:  pointer)  :  PtrInt

    Visibility:   default

Description:     SysFreemSize is the system memory manager implementation for MemSize (1271   )

    See also:    MemSize (1271   )
                29.9.317           SysReAllocMem

    Synopsis:    System memory manager:  Reallocate memory

Declaration:     function  SysReAllocMem(var  p:  pointer;size:  PtrInt)  :  Pointer

    Visibility:   default

Description:     SysReallocMem is a help routine for the system memory manager implementation for Re-
                AllocMem (1307   ).

    See also:    ReAllocMem (1307   )



                                                                                1331

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.318           SysResetFPU

    Synopsis:    Reset the floating point unit.

Declaration:     procedure  SysResetFPU

    Visibility:   default

Description:     SysResetFPU resets the floating point unit.  There should normally be no need to call this
                unit; the compiler itself takes care of this.
                29.9.319           SysSetCtrlBreakHandler

    Synopsis:    System CTRL-C handler

Declaration:     function  SysSetCtrlBreakHandler(Handler:  TCtrlBreakHandler)
                                                                     :  TCtrlBreakHandler

    Visibility:   default

Description:     SysSetCtrlBreakHandler sets the CTRL-C handler to the Handler callback, and returns
                the previous value of the handler.

    See also:    TCtrlBreakHandler (1197   )
                29.9.320           SysTryResizeMem

    Synopsis:    System memory manager:  attempt to resize memory.

Declaration:     function  SysTryResizeMem(var  p:  pointer;size:  PtrInt)  :  Boolean

    Visibility:   default

Description:     SysTryResizeMem  is  a  help  routine  for  the  system  memory  manager  implementation  for
                ReAllocMem (1307   ), SysReAllocMem (1331   )

    See also:    SysReAllocMem (1331   ), ReAllocMem (1307   )
                29.9.321           ThreadGetPriority

    Synopsis:    Return the priority of a thread.

Declaration:     function  ThreadGetPriority(threadHandle:  TThreadID)  :  LongInt

    Visibility:   default

Description:     ThreadGetPriority returns the priority of thread TThreadID to Prio.  The returned prior-
                ity is a value between -15 and 15.

       Errors:   None.

    See also:    ThreadSetPriority (1333   )


                                                                                1332

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.322           ThreadSetPriority

    Synopsis:    Set the priority of a thread.

Declaration:     function  ThreadSetPriority(threadHandle:  TThreadID;Prio:  LongInt)
                                                             :  Boolean

    Visibility:   default

Description:     ThreadSetPriority  sets  the  priority  of  thread  TThreadID  to  Prio.   Priority  is  a  value
                between -15 and 15.

       Errors:   None.

    See also:    ThreadGetPriority (1332   )
                29.9.323           ThreadSwitch

    Synopsis:    Signal possibility of thread switch

Declaration:     procedure  ThreadSwitch

    Visibility:   default

Description:     ThreadSwitch signals the operating system that the thread should be suspended and that
                another thread should be executed.

                This call is a hint only, and may be ignored.

    See also:    SuspendThread (1328   ), ResumeThread (1309   ), KillThread (1266   )
                29.9.324           trunc

    Synopsis:    Truncate a floating point value.

Declaration:     function  trunc(d:  ValReal)  :  Int64

    Visibility:   default

Description:     Trunc returns the integer part of X, which is always smaller than (or equal to) X in absolute
                value.

       Errors:   None.

    See also:    Frac (1248   ), Int (1262   ), Round (1311   )


                Listing:  ./refex/ex70.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   Program       t o  d e m o n s t r a t et h e  Trunc      f u n c t i o n. }


                 b e g i n
                    W r i t e l n ( Trunc    ( 1 2 3 . 4 5 6 ) ) ; {   P r i n t s 1 2 3   }
                    W r i t e l n ( Trunc    ( - 1 2 3 . 4 5 6 ) ) ;{  P r i n t s-123     }
                    W r i t e l n ( Trunc    ( 1 2 . 3 4 5 6 ) ) ; {   P r i n t s 1 2     }
                    W r i t e l n ( Trunc    ( - 1 2 . 3 4 5 6 ) ) ;{  P r i n t s-12      }
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                1333

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.325           Truncate

    Synopsis:    Truncate the file at position

Declaration:     procedure  Truncate(var  F:  File)

    Visibility:   default

Description:     Truncate truncates the (opened) file F at the current file position.

       Errors:   Depending  on  the  state  of  the  \var{\{\$I\}}  switch,  a  runtime  error  can  be  generated  if
                there is an error.  In the \var{\{\$I-\}} state, use IOResult to check for errors.

    See also:    Append (1214   ), Filepos (1242   ), Seek (1314   )


                Listing:  ./refex/ex71.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 1;


                {   Program       t o  d e m o n s t r a t et h e  T r u n c a t e f u n c t i o n. }


                Var    F   :   F i l e o f   l o n g i n t;
                        I, L   :  L o n g i n t;


                 b e g i n
                    A s s i g n ( F , 't e s t. tmp  ' ) ;
                    R e w r i t e (F  ) ;
                    For    I : = 1  t o  1 0  Do
                       Write      (F  ,I ) ;
                    W r i t e l n ( ' F i l e s i z eb e f o r e T r u n c a t e :   ' ,F i l e S i z e(F ) ) ;
                    C l o s e ( f ) ;
                    R e s e t ( F ) ;
                    Repeat
                       Read     ( F , I) ;
                    U n t i l  i=5;
                    Truncate        (F ) ;
                    W r i t e l n ( ' F i l e s i z ea f t e r  T r u n c a t e  :   ' ,F i l e s i z e(F ) ) ;
                    C l o s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.326           UCS4StringToWideString

    Synopsis:

Declaration:     function  UCS4StringToWideString(const  s:  UCS4String)  :  WideString

    Visibility:   default

Description:

       Errors:
                29.9.327           Unassigned

    Synopsis:    Unassigned variant.

Declaration:     function  Unassigned  :  Variant

    Visibility:   default



                                                                                1334

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.328           UnicodeToUtf8

    Synopsis:

Declaration:     function  UnicodeToUtf8(Dest:  PChar;Source:  PWideChar;MaxBytes:  SizeInt)
                                                      :  SizeInt
                function  UnicodeToUtf8(Dest:  PChar;MaxDestBytes:  SizeUInt;
                                                     Source:  PWideChar;SourceChars:  SizeUInt)
                                                      :  SizeUInt

    Visibility:   default

Description:

       Errors:
                29.9.329           UniqueString

    Synopsis:    Make sure reference count of string is 1

Declaration:     procedure  UniqueString(var  S:  AnsiString)
                procedure  UniqueString(var  S:  WideString)

    Visibility:   default

Description:     UniqueString ensures that the ansistring S has reference count 1.  It makes a copy of  S if
                this is necesary, and returns the copy in S

       Errors:   None.
                29.9.330           UnlockResource

    Synopsis:    Unlock a previously locked resource

Declaration:     function  UnlockResource(ResData:  HGLOBAL)  :  LongBool

    Visibility:   default

Description:     UnlockResource  unlocks  a  previously  locked  resource.   Note  that  this  function  does  not
                exist on windows, it's only needed on other platforms.

       Errors:   The function returns False if it failed.

    See also:    FindResource  (1246   ),  FreeResource  (1249   ),  SizeofResource  (1322   ),  LoadResource  (1269   ),
                lockResource (1269   ), FreeResource (1249   )
                29.9.331           upCase

    Synopsis:    Convert a string to all uppercase.

Declaration:     function  upCase(const  s:  shortstring)  :  shortstring
                function  upCase(c:  Char)  :  Char
                function  upcase(const  s:  ansistring)  :  ansistring
                function  UpCase(const  s:  WideString)  :  WideString

    Visibility:   default



                                                                                1335

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     Upcase returns the uppercase version of its argument C. If its argument is a string, then the
                complete string is converted to uppercase.  The type of the returned value is the same as the
                type of the argument.

       Errors:   None.

    See also:    Lowercase (1270   )


                Listing:__./refex/ex72.pp__________________________________________________________________________________________*
 *___________

                program       E x a m p l e 7 2;


                {   Program       t o  d e m o n s t r a t et h e  u p c a s e f u n c t i o n.  }


                 v a r c : c h a r;


                 b e g i n
                    f o r  c :=  'a '  t o   'z '  do
                        w r i t e(u p c a s e(c ) ) ;
                    W r i t e l n;
                    {   T h i s d o e s n' t  work     i n  TP  ,  b u t  i t  d o e s  i n  F r e e  P a s c a l }
                    W r i t e l n(u p c a s e( 'a b c d e f g h i j k l m n o p q r s t u v w x'y)z) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.332           UTF8Decode

    Synopsis:

Declaration:     function  UTF8Decode(const  s:  UTF8String)  :  WideString

    Visibility:   default

Description:

       Errors:
                29.9.333           UTF8Encode

    Synopsis:

Declaration:     function  UTF8Encode(const  s:  WideString)  :  UTF8String

    Visibility:   default

Description:

       Errors:
                29.9.334           Utf8ToAnsi

    Synopsis:

Declaration:     function  Utf8ToAnsi(const  s:  UTF8String)  :  ansistring

    Visibility:   default

Description:

       Errors:



                                                                                1336

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.335           Utf8ToUnicode

    Synopsis:

Declaration:     function  Utf8ToUnicode(Dest:  PWideChar;Source:  PChar;MaxChars:  SizeInt)
                                                      :  SizeInt
                function  Utf8ToUnicode(Dest:  PWideChar;MaxDestChars:  SizeUInt;
                                                     Source:  PChar;SourceBytes:  SizeUInt)  :  SizeUInt

    Visibility:   default

Description:

       Errors:
                29.9.336           Val

    Synopsis:    Calculate numerical value of a string.

Declaration:     procedure  Val(const  S:  String;var  V;var  Code:  Word)

    Visibility:   default

Description:     Val converts the value represented in the string S to a numerical value, and stores this value
                in  the  variable  V,  which  can  be  of  type  Longint,  Real  and  Byte.   If  the  conversion  isn't
                succesfull, then the parameter Code contains the index of the character in S which prevented
                the  conversion.  The  string  S  is  allowed  to  contain  spaces  in  the  beginning.  The  string  S
                can contain a number in decimal, hexadecimal, binary or octal format, as described in the
                language reference.

       Errors:   If the conversion doesn't succeed, the value of  Code indicates the position where the con-
                version went wrong.  The value of  V is then undefined.

    See also:    Str (1325   )


                Listing:  ./refex/ex74.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 4;


                {   Program       t o  d e m o n s t r a t et h e  V a l  f u n c t i o n. }
                Var     I ,  Code     :  I n t e g e r;


                 b e g i n
                    Val    ( ParamStr       ( 1 ) ,I , Code   ) ;
                    I f  Code   <>0    then
                        W r i t e l n(  'E r r o r a t   p o s i t i o n ', code   , '  :   ' ,Paramstr      ( 1 ) [Code   ] )
                    e l s e
                        W r i t e l n(  'V a l u e  :  ' , I) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.9.337           VarArrayGet

    Synopsis:

Declaration:     function  VarArrayGet(const  A:  Variant;const  Indices:  Array  of  SizeInt)
                                                   :  Variant

    Visibility:   default



                                                                                1337

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:

       Errors:
                29.9.338           VarArrayPut

    Synopsis:    Put a value in a single cell of a variant array

Declaration:     procedure  VarArrayPut(var  A:  Variant;const  Value:  Variant;
                                                   const  Indices:  Array  of  SizeInt)

    Visibility:   default

Description:     VarArrayPut puts Value in the variant array A at the location indicated by Indices.  Thus
                the statement


                VarArrayPut(A,B,[2,1]);


                is equivalent to


                A[2,1]:=B;


                The  difference  is  that  the  previous  is  usable  when  the  amount  of  indices  is  not  known  at
                compile time.

       Errors:   If the number of indices is wrong (or out of range) an exception may be raised.

    See also:    VarArrayGet (1337   )
                29.9.339           VarArrayRedim

    Synopsis:    Redimension a variant array

Declaration:     procedure  VarArrayRedim(var  A:  Variant;HighBound:  SizeInt)

    Visibility:   default

Description:     VarArrayRedim re-sizes the first dimension of the variant array A, giving it a new high bound
                HighBound.  Obviously, A must be a variant array for this function to work.

       Errors:
                29.9.340           VarCast

    Synopsis:

Declaration:     procedure  VarCast(var  dest:  variant;const  source:  variant;
                                            vartype:  LongInt)

    Visibility:   default

Description:

       Errors:



                                                                                1338

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.9.341           WaitForThreadTerminate

    Synopsis:    Wait for a thread to terminate.

Declaration:     function  WaitForThreadTerminate(threadHandle:  TThreadID;
                                                                   TimeoutMs:  LongInt)  :  DWord

    Visibility:   default

Description:     WaitForThreadTerminate  waits  for  a  thread  to  finish  its  execution.  The  thread  is  iden-
                tified  by  it's  handle  or  ID  threadHandle.   If  the  thread  does  not  exit  within  TimeoutMs
                milliseconds, the function will return with an error value.

                The function returns the exit code of the thread.

    See also:    EndThread (1236   ), KillThread (1266   )
                29.9.342           WideCharLenToString

    Synopsis:    Convert a length-limited array of widechar to an ansistring

Declaration:     function  WideCharLenToString(S:  PWideChar;Len:  SizeInt)  :  AnsiString

    Visibility:   default

Description:     WideCharLenToString converts at most Len widecharacters from the null-terminated widechar
                array S to an ansistring, and returns the ansistring.

       Errors:   No validity checking is performed on S. Passing an invalid pointer may lead to access viola-
                tions.

    See also:    StringToWideChar (1326   ), WideCharToString (1339   ), WideCharToStrVar (1340   ), WideCharLen-
                ToStrVar (1339   )
                29.9.343           WideCharLenToStrVar

    Synopsis:    Convert a length-limited array of widechar to an ansistring

Declaration:     procedure  WideCharLenToStrVar(Src:  PWideChar;Len:  SizeInt;
                                                                out  Dest:  AnsiString)

    Visibility:   default

Description:     WideCharLenToString converts at most Len widecharacters from the null-terminated widechar
                array Src to an ansistring, and returns the ansistring in Dest.

       Errors:   No  validity  checking  is  performed  on  Src.  Passing  an  invalid  pointer  may  lead  to  access
                violations.

    See also:    StringToWideChar (1326   ), WideCharToString (1339   ), WideCharToStrVar (1340   ), WideCharLen-
                ToString (1339   )
                29.9.344           WideCharToString

    Synopsis:    Convert a null-terminated array of widechar to an ansistring

Declaration:     function  WideCharToString(S:  PWideChar)  :  AnsiString

    Visibility:   default



                                                                                1339

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     WideCharToString  converts  the  null-terminated  widechar  array  S  to  an  ansistring,  and
                returns the ansistring.

       Errors:   No  validity  checking  is  performed  on  Src.   Passing  an  invalid  pointer,  or  an  improperly
                terminated array may lead to access violations.

    See also:    StringToWideChar (1326   ), WideCharToStrVar (1340   ), WideCharLenToStrVar (1339   ), WideCharLen-
                ToString (1339   )
                29.9.345           WideCharToStrVar

    Synopsis:    Convert a null-terminated array of widechar to an ansistring

Declaration:     procedure  WideCharToStrVar(S:  PWideChar;out  Dest:  AnsiString)

    Visibility:   default

Description:     WideCharToString  converts  the  null-terminated  widechar  array  S  to  an  ansistring,  and
                returns the ansistring in Dest.

       Errors:   No validity checking is performed on S. Passing an invalid pointer, or an improperly termi-
                nated array may lead to access violations.

    See also:    StringToWideChar (1326   ), WideCharToString (1339   ), WideCharToStrVar (1340   ), WideCharLen-
                ToString (1339   )
                29.9.346           WideStringToUCS4String

    Synopsis:    Convert a widestring to a UCS-4 encoded string.

Declaration:     function  WideStringToUCS4String(const  s:  WideString)  :  UCS4String

    Visibility:   default

Description:     Convert a widestring to a UCS-4 encoded string.

       Errors:
                29.9.347           Write

    Synopsis:    Write variable to a text file

Declaration:     procedure  Write(Args:  Arguments)
                procedure  Write(var  F:  Text;Args:  Arguments)

    Visibility:   default

Description:     Write writes the contents of the variables V1,  V2 etc.  to the file F. F can be a typed file,
                or a Text file.  If  F is a typed file, then the variables V1, V2 etc.  must be of the same type
                as  the  type  in  the  declaration  of  F.  Untyped  files  are  not  allowed.   If  the  parameter  F  is
                omitted, standard output is assumed.  If  F is of type Text, then the necessary conversions
                are done such that the output of the variables is in human-readable format.  This conversion
                is done for all numerical types.  Strings are printed exactly as they are in memory, as well
                as  PChar  types.   The  format  of  the  numerical  conversions  can  be  influenced  through  the
                following  modifiers:  OutputVariable  :    NumChars  [:    Decimals  ]   This  will  print  the
                value  of  OutputVariable  with  a  minimum  of  NumChars  characters,  from  which  Decimals
                are reserved for the decimals.  If the number cannot be represented with NumChars characters,



                                                                                1340

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                NumChars will be increased, until the representation fits.  If the representation requires less
                than NumChars characters then the output is filled up with spaces, to the left of the generated
                string, thus resulting in a right-aligned representation.  If no formatting is specified, then the
                number is written using its natural length, with nothing in front of it if it's positive, and a
                minus sign if it's negative.  Real numbers are, by default, written in scientific notation.

       Errors:   If an error occurs, a run-time error is generated.  This behavior can be controlled with the
                \var{\{\$i\}} switch.

    See also:    WriteLn (1341   ), Read (1304   ), Readln (1306   ), Blockwrite (1221   )
                29.9.348           WriteBarrier

    Synopsis:    Memory write barrier

Declaration:     procedure  WriteBarrier

    Visibility:   default

Description:     WriteBarrier is a low-level instruction to force a write barrier in the CPU: write (store)
                operations before and after the barrier are separate.

    See also:    ReadBarrier (1305   ), ReadDependencyBarrier (1305   ), ReadWriteBarrier (1306   )
                29.9.349           WriteLn

    Synopsis:    Write variable to a text file and append newline

Declaration:     procedure  Writeln(Args:  Arguments)
                procedure  WriteLn(var  F:  Text;Args:  Arguments)

    Visibility:   default

Description:     WriteLn does the same as Write (1340   ) for text files, and emits a Carriage Return - LineFeed
                character pair after that.  If the parameter F is omitted, standard output is assumed.  If no
                variables are specified, a Carriage Return - LineFeed character pair is emitted, resulting in
                a new line in the file F.

 Remark:          Under  linux  and  unix,  the  Carriage  Return  character  is  omitted,  as  customary  in  Unix
                environments.

       Errors:   If an error occurs, a run-time error is generated.  This behavior can be controlled with the
                \var{\{\$i\}} switch.

    See also:    Write (1340   ), Read (1304   ), Readln (1306   ), Blockwrite (1221   )


                Listing:  ./refex/ex75.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 5;


                {   Program       t o  d e m o n s t r a t et h e  W r i t e( l n)   f u n c t i o n. }


                Var
                    F   :  F i l e  o f  L o n g i n t;
                    L   :  L o n g i n t;


                 b e g i n
                    Write     (  'T h i s  i s  on   t h e  f i r s t  l i n e !   ' ) ;  {  No   CR  /LF    p a i r!  }
                                                                                1341

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                    W r i t e l n ( 'And     t h i s t o o . . .' ) ;
                    W r i t e l n ( 'But     t h i s i s   a l r e a d yon    t h e  s e c o n d l i n e. . .' ) ;
                    A s s i g n ( f , 't e s t. tmp  ' ) ;
                    R e w r i t e ( f ) ;
                    For    L : = 1  t o  1 0  do
                        w r i t e (F  ,L ) ;  {  No    w r i t e l n a l l o w e d h e r e  !  }
                    C l o s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                29.10            IDispatch



                29.10.1          Description

                IDispatch is the pascal definition of the Windows Dispatch interface definition.
                29.10.2          Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  1342      GetIDsOfNames                 Return IDs of named procedures
                  1342      GetTypeInfo                   Return type information about properties
                  1342      GetTypeInfoCount              Return number of properties.
                __1343______Invoke________________________Invoke_a_dispatch_method_________________________________________________*
 *___________
                29.10.3          IDispatch.GetTypeInfoCount

    Synopsis:    Return number of properties.

Declaration:     function  GetTypeInfoCount(out  count:  LongInt)  :  HRESULT

    Visibility:   default
                29.10.4          IDispatch.GetTypeInfo

    Synopsis:    Return type information about properties

Declaration:     function  GetTypeInfo(Index:  LongInt;LocaleID:  LongInt;out  TypeInfo)
                                                   :  HRESULT

    Visibility:   default
                29.10.5          IDispatch.GetIDsOfNames

    Synopsis:    Return IDs of named procedures

Declaration:     function  GetIDsOfNames(const  iid:  TGuid;names:  Pointer;
                                                     NameCount:  LongInt;LocaleID:  LongInt;
                                                     DispIDs:  Pointer)  :  HRESULT

    Visibility:   default

Description:     Return the ID of a procedure.



                                                                                1342

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.10.6          IDispatch.Invoke

    Synopsis:    Invoke a dispatch method

Declaration:     function  Invoke(DispID:  LongInt;const  iid:  TGuid;LocaleID:  LongInt;
                                         Flags:  Word;var  params;VarResult:  pointer;
                                         ExcepInfo:  pointer;ArgErr:  pointer)  :  HRESULT

    Visibility:   default
                29.11            IInvokable



                29.11.1          Description

                IInvokable is a descendent of IInterface (1189   ), compiled in the {$M+} state, so Run-Time
                Type Information (RTTI) is generated for it.
                29.12            IUnknown



                29.12.1          Description

                IUnknown is defined by windows.  It's the basic interface which all COM objects must imple-
                ment.  The definition does not contain any code.
                29.12.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  1343       _AddRef                 Increase reference count of the interface
                  1344       _Release                Decrease reference count of the interface
                __1343______QueryInterface___________Return_pointer_to_VMT_table_of_interface______________________________________*
 *___________
                29.12.3          IUnknown.QueryInterface

    Synopsis:    Return pointer to VMT table of interface

Declaration:     function  QueryInterface(const  iid:  TGuid;out  obj)  :  LongInt

    Visibility:   default
                29.12.4          IUnknown.__AddRef

    Synopsis:    Increase reference count of the interface

Declaration:     function  _AddRef  :  LongInt

    Visibility:   default

    See also:    IUnknown._Release (1344   )

                                                                                1343

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.12.5          IUnknown.__Release

    Synopsis:    Decrease reference count of the interface

Declaration:     function  _Release  :  LongInt

    Visibility:   default

    See also:    IUnknown._AddRef (1343   )
                29.13            TAggregatedOb ject



                29.13.1          Description

                TAggregatedObject implements an object whose lifetime is governed by an external object
                (or  interface).   It  does  not  implement  the  IUnknown  interface  by  itself,  but  delegates  all
                methods to the controller object, as exposed in the Controller (1345   ) property.  In effect, the
                reference count of the aggregated object is the same as that of it's controller, and additionally,
                all interfaces of the controller are exposed by the aggregated object.

                Note that the aggregated object maintains a non-counted reference to the controller.

                Aggregated  objects  should  be  used  when  using  delegation  to  implement  reference  counted
                objects:  the delegated interfaces can be implemented safely by TAggregatedObject descen-
                dents.
                29.13.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __1344______Create__________Create_a_new_instance_of__TAggregatedObject____________________________________________*
 *___________
                29.13.3          Property  overview

                __Page______Property__________Access_______Description_____________________________________________________________*
 *___________
                __1345______Controller________r____________Controlling_instance____________________________________________________*
 *___________
                29.13.4          TAggregatedObject.Create

    Synopsis:    Create a new instance of  TAggregatedObject

Declaration:     constructor  Create(const  aController:  IUnknown)

    Visibility:   public

Description:     Create creates a new instance of  TAggregatedObject on the heap, and stores a reference
                to aController, so it can be exposed in the Controller (1345   ) property.

       Errors:   If not enough memory is present on the heap, an exception will be raised.  If the aController
                is  Nil,  exceptions  will  occur  when  any  of  the  TAggregatedObject  methods  (actually,  the
                IUnknown methods) are used.

    See also:    TAggregatedObject.Controller (1345   )



                                                                                1344

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.13.5          TAggregatedObject.Controller

    Synopsis:    Controlling instance

Declaration:     Property  Controller  :  IUnknown

    Visibility:   public

      Access:    Read

Description:     Controller exposes the controlling object, with all interfaces it has.

                The value of the controller is set when the TAggregatedObject instance is created.

    See also:    TAggregatedObject.Create (1344   )
                29.14            TContainedOb ject



                29.14.1          Description

                TContainedObject is the base class for contained objects, i.e.  objects that do not implement
                a  reference  counting  mechanism  themselves,  but  are  owned  by  some  other  object  which
                handles the reference counting mechanism.  It implements the IUnknown interface and, more
                specifically, the QueryInterface method of  IUnknown.
                29.15            TInterfacedOb ject



                29.15.1          Description

                TInterfacedObject  is  a  descendent  of  TObject  (1346   )  which  implements  the  IUnknown
                (1343   ) interface.  It can be used as a base class for all classes which need reference counting.
                29.15.2          Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  1345      AfterConstruction            Handle reference count properly.
                  1346      BeforeDestruction            Check reference count.
                __1346______NewInstance__________________Create_a_new_instance_____________________________________________________*
 *___________
                29.15.3          Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __1346______RefCount_________r____________Return_the_current_reference_count_______________________________________*
 *___________
                29.15.4          TInterfacedObject.AfterConstruction

    Synopsis:    Handle reference count properly.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction overrides the basic method in TObject and adds some additional ref-
                erence count handling.

                                                                                1345

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
       Errors:   None.

    See also:    TInterfacedObject.BeforeDestruction (1346   )
                29.15.5          TInterfacedObject.BeforeDestruction

    Synopsis:    Check reference count.

Declaration:     procedure  BeforeDestruction;    Override

    Visibility:   public

Description:     AfterConstruction  overrides  the  basic  method  in  TObject  and  adds  a  reference  count
                check:  if the reference count is not zero, an error occurs.

       Errors:   A runtime-error 204 will be generated if the reference count is nonzero when the object is
                destroyed.

    See also:    TInterfacedObject.AfterConstruction (1345   )
                29.15.6          TInterfacedObject.NewInstance

    Synopsis:    Create a new instance

Declaration:     function  NewInstance  :  TObject;    Override

    Visibility:   public

Description:     NewInstance initializes a new instance of TInterfacedObject (1345   )

       Errors:   None.
                29.15.7          TInterfacedObject.RefCount

    Synopsis:    Return the current reference count

Declaration:     Property  RefCount  :  LongInt

    Visibility:   public

      Access:    Read

Description:     RefCount returns the current reference count.  This reference count cannot be manipulated,
                except through the methods of IUnknown (1343   ).  When it reaches zero, the class instance
                is destroyed.

    See also:    IUnknown (1343   )
                29.16            TOb ject



                29.16.1          Description

                TObject is the parent root class for all classes in Object Pascal.  If a class has no parent class
                explicitly declared, it is dependent on TObject.  TObject introduces class methods that deal
                with the class' type information, and contains all necessary methods to create an instance at
                runtime, and to dispatch messages to the correct method (both string and integer messages).
                                                                                1346

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.2          Method  overview

                __Page______Property_____________________________Description_______________________________________________________*
 *___________
                  1353      AfterConstruction                    Method called after the constructor was called.
                  1353      BeforeDestruction                    Method called before the destructor is called.
                  1350      ClassInfo                            Return a pointer to the type information for this class.
                  1350      ClassName                            Return the current class name.
                  1350      ClassNameIs                          Check whether the class name equals the given name.
                  1351      ClassParent                          Return the parent class.
                  1350      ClassType                            Return a "class of" pointer for the current class
                  1349      CleanupInstance                      Finalize the class instance.
                  1347      Create                               TObject Constructor
                  1349      DefaultHandler                       Default handler for integer message handlers.
                  1353      DefaultHandlerStr                    Default handler for string messages.
                  1347      Destroy                              TObject destructor.
                  1352      Dispatch                             Dispatch an integer message
                  1352      DispatchStr                          Dispatch a string message.
                  1353      FieldAddress                         Return the address of a field.
                  1349      Free                                 Check for Nil and call destructor.
                  1348      FreeInstance                         Clean up instance and free the memory reserved for the
                                                                 instance.
                  1354      GetInterface                         Return a reference to an interface
                  1354      GetInterfaceByStr
                  1354      GetInterfaceEntry
                  1354      GetInterfaceEntryByStr
                  1355      GetInterfaceTable
                  1351      InheritsFrom                         Chck wether class is an ancestor.
                  1349      InitInstance                         Initialize a new class instance.
                  1351      InstanceSize                         Return the size of an instance.
                  1352      MethodAddress                        Return the address of a method
                  1352      MethodName                           Return the name of a method.
                  1348      newinstance                          Allocate memory on the heap for a new instance
                  1348      SafeCallException                    Handle exception object
                __1351______StringMessageTable___________________Return_a_pointer_to_the_string_message_table._____________________*
 *___________
                29.16.3          TObject.Create

    Synopsis:    TObject Constructor

Declaration:     constructor  Create

    Visibility:   public

Description:     Create creates a new instance of TObject.  Currently it does nothing.  It is also not virtual,
                so there is in principle no need to call it directly.

    See also:    TObject.Destroy (1347   )
                29.16.4          TObject.Destroy

    Synopsis:    TObject destructor.

Declaration:     destructor  Destroy;    Virtual

    Visibility:   public
                                                                                1347

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     Destroy is the destructor of TObject.  It will clean up the memory assigned to the instance.
                Descendent classes should override destroy if they want to do additional clean-up.  No other
                destructor should be implemented.

                It is bad programming practice to call Destroy directly.  It is better to call the Free (1349   )
                method, because that one will check first if  Self is different from Nil.

                To clean up an instance and reset the refence to the instance, it is best to use the FreeAndNil
                (1443   ) function.

    See also:    TObject.Create (1347   ), TObject.Free (1349   )
                29.16.5          TObject.newinstance

    Synopsis:    Allocate memory on the heap for a new instance

Declaration:     function  newinstance  :  TObject;    Virtual

    Visibility:   public

Description:     NewInstance allocates memory on the heap for a new instance of the current class.  If the
                memory  was  allocated,  the  class  will  be  initialized  by  a  call  to  InitInstance  (1349   ).   The
                function returns the newly initialized instance.

       Errors:   If not enough memory is available, a Nil pointer may be returned, or an exception may be
                raised.

    See also:    TObject.Create  (1347   ),  TObject.InitInstance  (1349   ),  TObject.InstanceSize  (1351   ),  TOb-
                ject.FreeInstance (1348   )
                29.16.6          TObject.FreeInstance

    Synopsis:    Clean up instance and free the memory reserved for the instance.

Declaration:     procedure  FreeInstance;    Virtual

    Visibility:   public

Description:     FreeInstance  cleans  up  an  instance  of  the  current  class,  and  releases  the  heap  memory
                occupied by the class instance.

    See also:    TObject.Destroy (1347   ), TObject.InitInstance (1349   ), TObject.NewInstance (1348   )
                29.16.7          TObject.SafeCallException

    Synopsis:    Handle exception object

Declaration:     function  SafeCallException(exceptobject:  TObject;exceptaddr:  pointer)
                                                             :  LongInt;    Virtual

    Visibility:   public

Description:     SafeCallException should be overridden to handle exceptions in a method marked with
                the savecall directive.  The implementation in TObject simply returns zero.


                                                                                1348

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.8          TObject.DefaultHandler

    Synopsis:    Default handler for integer message handlers.

Declaration:     procedure  DefaultHandler(var  message);    Virtual

    Visibility:   public

Description:     DefaultHandler is the default handler for messages.  If a message has an unknown message
                ID (i.e.  does not appear in the table with integer message handlers), then it will be passed
                to DefaultHandler by the Dispatch (1352   ) method.

       Errors:

    See also:    TObject.Dispatch (1352   ), TObject.DefaultHandlerStr (1353   )
                29.16.9          TObject.Free

    Synopsis:    Check for Nil and call destructor.

Declaration:     procedure  Free

    Visibility:   public

Description:     Free will check the Self pointer and calls Destroy (1347   ) if it is different from Nil.  This is
                a safer method than calling Destroy directly.  If a reference to the object must be reset as
                well (a recommended technque), then the function FreeAndNil (1443   ) should be called.

       Errors:   None.

    See also:    TObject.Destroy (1347   ), #rtl.sysutils.freeandnil (1443   )
                29.16.10           TObject.InitInstance

    Synopsis:    Initialize a new class instance.

Declaration:     function  InitInstance(instance:  pointer)  :  TObject

    Visibility:   public

Description:     InitInstance initializes the memory pointer to by Instance.  This means that the VMT
                is initialized, and the interface pointers are set up correctly.  The function returns the newly
                initialized instance.

    See also:    TObject.NewInstance (1348   ), TObject.Create (1347   )
                29.16.11           TObject.CleanupInstance

    Synopsis:    Finalize the class instance.

Declaration:     procedure  CleanupInstance

    Visibility:   public

Description:     CleanUpinstance finalizes the instance, i.e.  takes care of all reference counted objects, by
                decreasing their reference count by 1, and freeing them if their count reaches zero.

                Normally,  CleanupInstance  should  never  be  called,  it  is  called  automatically  when  the
                object is freed with it's constructor.

       Errors:   None.

    See also:    TObject.Destroy (1347   ), TObject.Free (1349   ), TObject.InitInstance (1349   )



                                                                                1349

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.12           TObject.ClassType

    Synopsis:    Return a "class of" pointer for the current class

Declaration:     function  ClassType  :  TClass

    Visibility:   public

Description:     ClassType returns a TClass (1197   ) class type reference for the current class.

    See also:    TClass (1197   ), TObject.ClassInfo (1350   ), TObject.ClassName (1350   )
                29.16.13           TObject.ClassInfo

    Synopsis:    Return a pointer to the type information for this class.

Declaration:     function  ClassInfo  :  pointer

    Visibility:   public

Description:     ClassInfo returns a pointer to the type information for this class.  This pointer can be used
                in the various type information routines.
                29.16.14           TObject.ClassName

    Synopsis:    Return the current class name.

Declaration:     function  ClassName  :  shortstring

    Visibility:   public

Description:     ClassName returns the class name for the current class, in all-uppercase letters.  To check
                for the class name, use the ClassNameIs (1350   ) class method.

       Errors:   None.

    See also:    TObject.ClassInfo (1350   ), TObject.ClassType (1350   ), TObject.ClassNameIs (1350   )
                29.16.15           TObject.ClassNameIs

    Synopsis:    Check whether the class name equals the given name.

Declaration:     function  ClassNameIs(const  name:  String)  :  Boolean

    Visibility:   public

Description:     ClassNameIs checks whether Name equals the class name.  It takes of case sensitivity, i.e.  it
                converts both names to uppercase before comparing.

    See also:    TObject.ClassInfo (1350   ), TObject.ClassType (1350   ), TObject.ClassName (1350   )


                                                                                1350

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.16           TObject.ClassParent

    Synopsis:    Return the parent class.

Declaration:     function  ClassParent  :  TClass

    Visibility:   public

Description:     ClassParent returns the class of the parent class of the current class.  This is always different
                from Nil, except for TObject.

       Errors:   None.

    See also:    TObject.ClassInfo (1350   ), TObject.ClassType (1350   ), TObject.ClassName (1350   )
                29.16.17           TObject.InstanceSize

    Synopsis:    Return the size of an instance.

Declaration:     function  InstanceSize  :  SizeInt

    Visibility:   public

Description:     InstanceSize returns the number of bytes an instance takes in memory.  This is Just the
                memory  occupied  by  the  class  structure,  and  does  not  take  into  account  any  additional
                memory that might be allocated by the constructor of the class.

       Errors:   None.

    See also:    TObject.InitInstance (1349   ), TObject.ClassName (1350   ), TObject.ClassInfo (1350   ), TOb-
                ject.ClassType (1350   )
                29.16.18           TObject.InheritsFrom

    Synopsis:    Chck wether class is an ancestor.

Declaration:     function  InheritsFrom(aclass:  TClass)  :  Boolean

    Visibility:   public

Description:     InheritsFrom returns True if AClass is an ancestor class from the current class, and returns
                false if it is not.

       Errors:

    See also:    TObject.ClassName (1350   ), TObject.ClassInfo (1350   ), TObject.ClassType (1350   ), TClass
                (1197   )
                29.16.19           TObject.StringMessageTable

    Synopsis:    Return a pointer to the string message table.

Declaration:     function  StringMessageTable  :  pstringmessagetable

    Visibility:   public

Description:     StringMessageTable returns a pointer to the string message table, which can be used to
                look  up  methods  for  dispatching  a  string  message.   It  is  used  by  the  DispatchStr  (1352   )
                method.

       Errors:   If there are no string message handlers, nil is returned.

    See also:    TObject.DispatchStr (1352   ), TObject.Dispatch (1352   )



                                                                                1351

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.20           TObject.Dispatch

    Synopsis:    Dispatch an integer message

Declaration:     procedure  Dispatch(var  message)

    Visibility:   public

Description:     Dispatch  looks  in  the  message  handler  table  for  a  handler  that  handles  message.   The
                message is identified by the first dword (cardinal) in the message structure.

                If no matching message handler is found, the message is passed to the DefaultHandler (1349   )
                method, which can be overridden by descendent classes to add custom handling of messages.

    See also:    TObject.DispatchStr (1352   ), TObject.DefaultHandler (1349   )
                29.16.21           TObject.DispatchStr

    Synopsis:    Dispatch a string message.

Declaration:     procedure  DispatchStr(var  message)

    Visibility:   public

Description:     DispatchStr extracts the message identifier from Message and checks the message handler
                table to see if a handler for the message is found, and calls the handler, passing along the
                message.  If no handler is found, the default DefaultHandlerStr (1353   ) is called.

       Errors:   None.

    See also:    TObject.DefaultHandlerStr (1353   ), TObject.Dispatch (1352   ), TObject.DefaultHandler (1349   )
                29.16.22           TObject.MethodAddress

    Synopsis:    Return the address of a method

Declaration:     function  MethodAddress(const  name:  shortstring)  :  pointer

    Visibility:   public

Description:     MethodAddress returns the address of a method, searching the method by its name.  The
                Name  parameter  specifies  which  method  should  be  taken.   The  search  is  conducted  in  a
                case-insensitive manner.

       Errors:   If no matching method is found, Nil is returned.

    See also:    TObject.MethodName (1352   ), TObject.FieldAddress (1353   )
                29.16.23           TObject.MethodName

    Synopsis:    Return the name of a method.

Declaration:     function  MethodName(address:  pointer)  :  shortstring

    Visibility:   public

Description:     MethodName  searches  the  VMT  for  a  method  with  the  specified  address  and  returns  the
                name of the method.

       Errors:   If no method with the matching address is found, an empty string is returned.

    See also:    TObject.MethodAddress (1352   ), TObject.FieldAddress (1353   )



                                                                                1352

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.24           TObject.FieldAddress

    Synopsis:    Return the address of a field.

Declaration:     function  FieldAddress(const  name:  shortstring)  :  pointer

    Visibility:   public

Description:     FieldAddress returns the address of the field with name name.  The address is the address
                of the field in the current class instance.

       Errors:   If no field with the specified name is found, Nil is returned.

    See also:    TObject.MethodAddress (1352   ), TObject.MethodName (1352   )
                29.16.25           TObject.AfterConstruction

    Synopsis:    Method called after the constructor was called.

Declaration:     procedure  AfterConstruction;    Virtual

    Visibility:   public

Description:     AfterConstruction  is  a  method  called  after  the  constructor  was  called.  It  does  nothing
                in the implementation of  TObject and must be overridden by descendent classes to provide
                specific behaviour that is executed after the constructor has finished executing.  (for instance,
                call an event handler)

       Errors:   None.

    See also:    TObject.BeforeDestruction (1353   ), TObject.Create (1347   )
                29.16.26           TObject.BeforeDestruction

    Synopsis:    Method called before the destructor is called.

Declaration:     procedure  BeforeDestruction;    Virtual

    Visibility:   public

Description:     BeforeDestruction is a method called before the destructor is called.  It does nothing in the
                implementation of TObject and must be overridden by descendent classes to provide specific
                behaviour that is executed before the destructor has finished executing.  (for instance, call
                an event handler)

       Errors:   None.

    See also:    TObject.AfterConstruction (1353   ), TObject.Destroy (1347   ), TObject.Free (1349   )
                29.16.27           TObject.DefaultHandlerStr

    Synopsis:    Default handler for string messages.

Declaration:     procedure  DefaultHandlerStr(var  message);    Virtual

    Visibility:   public
                                                                                1353

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
Description:     DefaultHandlerStr  is  called  for  string  messages  which  have  no  handler  associated  with
                them  in  the  string  message  handler  table.  The  implementation  of  DefaultHandlerStr  in
                TObject does nothing and mut be overridden by descendent classes to provide specific mes-
                sage handling behaviour.

    See also:    TObject.DispatchStr (1352   ), TObject.Dispatch (1352   ), TObject.DefaultHandler (1349   )
                29.16.28           TObject.GetInterface

    Synopsis:    Return a reference to an interface

Declaration:     function  GetInterface(const  iid:  TGuid;out  obj)  :  Boolean

    Visibility:   public

Description:     GetInterface scans the interface tables and returns a reference to the interface iid.  The
                reference  is  stored  in  Obj  which  should  be  an  interface  reference.   It  returns  True  if  the
                interface was found, False if not.

                The reference count of the interface is increased by this call.

       Errors:   If no interface was found, False is returned.

    See also:    TObject.GetInterfaceByStr (1354   )
                29.16.29           TObject.GetInterfaceByStr

    Synopsis:

Declaration:     function  GetInterfaceByStr(const  iidstr:  String;out  obj)  :  Boolean

    Visibility:   public

Description:

       Errors:
                29.16.30           TObject.GetInterfaceEntry

    Synopsis:

Declaration:     function  GetInterfaceEntry(const  iid:  TGuid)  :  pinterfaceentry

    Visibility:   public

Description:

       Errors:
                29.16.31           TObject.GetInterfaceEntryByStr

    Synopsis:

Declaration:     function  GetInterfaceEntryByStr(const  iidstr:  String)  :  pinterfaceentry

    Visibility:   public

Description:

       Errors:



                                                                                1354

                __________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________
                29.16.32           TObject.GetInterfaceTable

    Synopsis:

Declaration:     function  GetInterfaceTable  :  pinterfacetable

    Visibility:   public

Description:

       Errors:

                                                                                1355


Chapter   30


Reference   for   unit   'sysutils'
30.1          Miscellaneous  conversion  routines


Functions for various conversions.



                                                       Table 30.1:

              __Name_____________________________Description____________________________________________________
                BCDToInt (1393   )               Convert BCD number to integer
                CompareMem (1396   )             Compare two memory regions
                FloatToStrF (1430   )            Convert float to formatted string
                FloatToStr (1429   )             Convert float to string
                FloatToText (1432   )            Convert float to string
                FormatFloat (1441   )            Format a floating point value
                GetDirs (1444   )                Split string in list of directories
                IntToHex (1451   )               return hexadecimal representation of integer
                IntToStr (1451   )               return decumal representation of integer
                StrToIntDef (1483   )            Convert string to integer with default value
                StrToInt (1482   )               Convert string to integer
                StrToFloat (1480   )             Convert string to float
                TextToFloat (1487   )            Convert null-terminated string to float



30.2          Date/time  routines


Functions for date and time handling.
30.3          FileName  handling  routines


Functions for file manipulation.
30.4          File  input/output  routines


Functions for reading/writing to file.



                                                            1356

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___

                                                       Table 30.2:

    _Name____________________________________________Description____________________________________________________________
      DateTimeToFileDate (1401   )                    Convert DateTime type to file date
      DateTimeToStr (1402   )                         Construct string representation of DateTime
      DateTimeToString (1402   )                      Construct string representation of DateTime
      DateTimeToSystemTime (1403   )                  Convert DateTime to system time
      DateTimeToTimeStamp (1404   )                   Convert DateTime to timestamp
      DateToStr (1404   )                             Construct string representation of date
      Date (1401   )                                  Get current date
      DayOfWeek (1405   )                             Get day of week
      DecodeDate (1405   )                            Decode DateTime to year month and day
      DecodeTime (1406   )                            Decode DateTime to hours, minutes and seconds
      EncodeDate (1410   )                            Encode year, day and month to DateTime
      EncodeTime (1410   )                            Encode hours, minutes and seconds to DateTime
      FormatDateTime (1441   )                        Return string representation of DateTime
      IncMonth (1450   )                              Add 1 to month
      IsLeapYear (1453   )                            Determine if year is leap year
      MSecsToTimeStamp (1456   )                      Convert nr of milliseconds to timestamp
      Now (1457   )                                   Get current date and time
      StrToDateTime (1479   )                         Convert string to DateTime
      StrToDate (1478   )                             Convert string to date
      StrToTime (1484   )                             Convert string to time
      SystemTimeToDateTime (1486   )                  Convert system time to datetime
      TimeStampToDateTime (1488   )                   Convert time stamp to DateTime
      TimeStampToMSecs (1489   )                      Convert Timestamp to number of millicseconds
      TimeToStr (1489   )                             return string representation of Time
      Time (1488   )                                  Get current tyme

30.5          PChar  related  functions


Most PChar functions are the same as their counterparts in the STRINGS unit.  The following
functions are the same :


    1.  StrCat (1464   ) :  Concatenates two PChar strings.

    2.  StrComp (1465   ) :  Compares two PChar strings.

    3.  StrCopy (1465   ) :  Copies a PChar string.

    4.  StrECopy (1466   ) :  Copies a PChar string and returns a pointer to the terminating null
        byte.

    5.  StrEnd (1467   ) :  Returns a pointer to the terminating null byte.

    6.  StrIComp (1468   ) :  Case insensitive compare of 2 PChar strings.

    7.  StrLCat (1470   ) :  Appends at most L characters from one PChar to another PChar.

    8.  StrLComp (1470   ) :  Case sensitive compare of at most L characters of 2 PChar strings.

    9.  StrLCopy (1471   ) :  Copies at most L characters from one PChar to another.

   10.  StrLen (1471   ) :  Returns the length (exclusive terminating null byte) of a PChar string.
                                                                1357

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___

                                                       Table 30.3:

         __Name________________________________________Description____________________________________________________
           AddDisk (1378   )                           Add sisk to list of disk drives
           ChangeFileExt (1395   )                     Change extension of file name
           CreateDir (1399   )                         Create a directory
           DeleteFile (1407   )                        Delete a file
           DiskFree (1408   )                          Free space on disk
           DiskSize (1408   )                          Total size of disk
           ExpandFileName (1413   )                    Create full file name
           ExpandUNCFileName (1414   )                 Create full UNC file name
           ExtractFileDir (1414   )                    Extract drive and directory part of filename
           ExtractFileDrive (1415   )                  Extract drive part of filename
           ExtractFileExt (1415   )                    Extract extension part of filename
           ExtractFileName (1415   )                   Extract name part of filename
           ExtractFilePath (1416   )                   Extrct path part of filename
           ExtractRelativePath (1416   )               Construct relative path between two files
           FileAge (1417   )                           Return file age
           FileDateToDateTime (1419   )                Convert file date to system date
           FileExists (1420   )                        Determine whether a file exists on disk
           FileGetAttr (1420   )                       Get attributes of file
           FileGetDate (1421   )                       Get date of last file modification
           FileSearch (1423   )                        Search for file in path
           FileSetAttr (1424   )                       Get file attributes
           FileSetDate (1425   )                       Get file dates
           FindFirst (1426   )                         Start finding a file
           FindNext (1427   )                          Find next file
           GetCurrentDir (1444   )                     Return current working directory
           RemoveDir (1458   )                         Remove a directory from disk
           RenameFile (1459   )                        Rename a file on disk
           SetCurrentDir (1461   )                     Set current working directory
           SetDirSeparators (1461   )                  Set directory separator characters
           FindClose (1426   )                         Stop searching a file
           DoDirSeparators (1409   )                   Replace directory separator characters

   11.  StrLIComp  (1473   )  :   Case  insensitive  compare  of  at  most  L  characters  of  2  PChar
        strings.

   12.  StrLower (1473   ) :  Converts a PChar to all lowercase letters.

   13.  StrMove (1474   ) :  Moves one PChar to another.

   14.  StrNew (1474   ) :  Makes a copy of a PChar on the heap, and returns a pointer to this
        copy.

   15.  StrPos (1476   ) :  Returns the position of one PChar string in another?

   16.  StrRScan (1476   ) :  returns a pointer to the last occurrence of on PChar string in another
        one.

   17.  StrScan (1477   ) :  returns a pointer to the first occurrence of on PChar string in another
        one.

   18.  StrUpper (1485   ) :  Converts a PChar to all uppercase letters.
                                                                1358

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___

                                                       Table 30.4:

                        __Name___________________________Description__________________________________
                          FileCreate (1418   )           Create a file and return handle
                          FileOpen (1422   )             Open file end return handle
                          FileRead (1423   )             Read from file
                          FileSeek (1424   )             Set file position
                          FileTruncate (1425   )         Truncate file length
                          FileWrite (1425   )            Write to file
                          FileClose (1418   )            Close file handle

The  subsequent  functions  are  different  from  their  counterparts  in  STRINGS,  although  the
same examples can be used.
30.6          Localization  support


Localization support depends on various constants and structures being initialized correctly.
On  Windows  and  OS/2  this  is  done  automatically:  a  widestring  manager  is  installed  by
default which helps taking care of the current locale when performing various operations on
strings.  The various internationalization settings (date/time format, currency, language etc)
are also initialized correctly on these platforms.

On unixes, the widestring support is in a separate unit:  cwstrings, which loads the various
needed  functions  from  the  C  library.   It  should  be  added  manually  to  the  uses  clause  of
your program.  No initialization settings are applied by this unit, these must be initialized
separately for the moment.
30.7          Formatting  strings


Functions for formatting strings.



                                                       Table 30.5:

           __Name__________________________________Description_____________________________________________________
             AdjustLineBreaks (1378   )            Convert line breaks to line breaks for system
             FormatBuf (1440   )                   Format a buffer
             Format (1434   )                      Format arguments in string
             FmtStr (1433   )                      Format buffer
             QuotedStr (1458   )                   Quote a string
             StrFmt (1467   )                      Format arguments in a string
             StrLFmt (1472   )                     Format maximum L characters in a string
             TrimLeft (1490   )                    Remove whitespace at the left of a string
             TrimRight (1491   )                   Remove whitespace at the right of a string
             Trim (1490   )                        Remove whitespace at both ends of a string

                                                                1359

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.8          String  functions


Functions for handling strings.



                                                       Table 30.6:

      __Name________________________________________Description__________________________________________________________
        AnsiCompareStr (1379   )                     Compare two strings
        AnsiCompareText (1380   )                    Compare two strings, case insensitive
        AnsiExtractQuotedStr (1381   )               Removes quotes from string
        AnsiLastChar (1382   )                       Get last character of string
        AnsiLowerCase (1383   )                      Convert string to all-lowercase
        AnsiQuotedStr (1384   )                      Qoutes a string
        AnsiStrComp (1385   )                        Compare strings case-sensitive
        AnsiStrIComp (1385   )                       Compare strings case-insensitive
        AnsiStrLComp (1387   )                       Compare L characters of strings case sensitive
        AnsiStrLIComp (1388   )                      Compare L characters of strings case insensitive
        AnsiStrLastChar (1386   )                    Get last character of string
        AnsiStrLower (1389   )                       Convert string to all-lowercase
        AnsiStrUpper (1390   )                       Convert string to all-uppercase
        AnsiUpperCase (1391   )                      Convert string to all-uppercase
        AppendStr (1392   )                          Append 2 strings
        AssignStr (1393   )                          Assign value of strings on heap
        CompareStr (1397   )                         Compare two strings case sensitive
        CompareText (1398   )                        Compare two strings case insensitive
        DisposeStr (1409   )                         Remove string from heap
        IsValidIdent (1453   )                       Is string a valid pascal identifier
        LastDelimiter (1454   )                      Last occurance of character in a string
        LeftStr (1455   )                            Get first N characters of a string
        LoadStr (1455   )                            Load string from resources
        LowerCase (1455   )                          Convert string to all-lowercase
        NewStr (1456   )                             Allocate new string on heap
        RightStr (1460   )                           Get last N characters of a string
        StrAlloc (1463   )                           Allocate memory for string
        StrBufSize (1463   )                         Reserve memory for a string
        StrDispose (1466   )                         Remove string from heap
        StrPas (1475   )                             Convert PChar to pascal string
        StrPCopy (1475   )                           Copy pascal string
        StrPLCopy (1476   )                          Copy N bytes of pascal string
        UpperCase (1496   )                          Convert string to all-uppercase



30.9          Used  units



30.10            Overview


This  documentation  describes  the  sysutils  unit.   The  sysutils  unit  was  started  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.

                                                                1360

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___

                                    Table 30.7:  Used units by unit 'sysutils'


                                                  __Name____________Page_____
                                                    errors           1356
                                                    sysconst         1356
                                                    Unix             1356
                                                    Unixtype         1356

30.11            Constants,  types  and  variables



30.11.1          Constants

ConfigExtension  :  String  =  '.cfg'


ConfigExtension is the default extension used by the GetAppConfigFile (1443   ) call.  It can
be set to any valid extension for the current OS.


DateDelta  =  693594


Days between 1/1/0001 and 12/31/1899


DriveDelim  =  DriveSeparator


DriveDelim refers to the system unit's DriveSeparator constant, it is for Delphi compati-
bility only.


EmptyStr  :  String  =  ''


Empty String Constant


EmptyWideStr  :  WideString  =  ''


Empty wide string.


faAnyFile  =  $0000003f


Use this attribute in the FindFirst (1426   ) call to find all matching files.


faArchive  =  $00000020


Attribute of a file, meaning the file has the archive bit set.  Used in TSearchRec (1372   ) and
FindFirst (1426   )


faDirectory  =  $00000010


Attribute of a file, meaning the file is a directory.  Used in TSearchRec (1372   ) and FindFirst
(1426   )


faHidden  =  $00000002



                                                                1361

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
Attribute of a file, meaning the file is read-only.  Used in TSearchRec (1372   ) and FindFirst
(1426   )


faReadOnly  =  $00000001


Attribute of a file, meaning the file is read-only.  Used in TSearchRec (1372   ) and FindFirst
(1426   )


faSymLink  =  $00000040


faSymLink  means  the  file  (as  returned  e.g.   by  FindFirst  (1426   )/FindNext  (1427   )),  is  a
symlink.  It's ignored under Windows.


faSysFile  =  $00000004


Attribute of a file, meaning the file is a system file.  Used in TSearchRec (1372   ) and FindFirst
(1426   )


faVolumeId  =  $00000008


Attribute of a file, meaning the file contains the volume ID. Used in TSearchRec (1372   ) and
FindFirst (1426   )


feInvalidHandle  :  THandle  =  THandle  (  -  1  )


feInvalidHandle is the return value of FileOpen (1422   ) in case of an error.


filerecnamelength  =  255


filerecnamelength describes the length of the FileRec (1368   ) filename field.


fmOpenRead  =  $0000


fmOpenRead is used in the FileOpen (1422   ) call to open a file in read-only mode.


fmOpenReadWrite  =  $0002


fmOpenReadWrite is used in the FileOpen (1422   ) call to open a file in read-write mode.


fmOpenWrite  =  $0001


fmOpenWrite is used in the FileOpen (1422   ) call to open a file in write-only mode.


fmShareCompat  =  $0000


fmOpenShareCompat is used in the FileOpen (1422   ) call OR-ed together with one of fmOpen-
ReadWrite (1362   ), fmOpenRead (1362   ) or fmOpenWrite (1362   ),to open a file in a sharing
modus that is equivalent to sharing implemented in MS-DOS.


fmShareDenyNone  =  $0040



                                                                1362

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
fmOpenShareExclusive  is  used  in  the  FileOpen  (1422   )  call  OR-ed  together  with  one  of
fmOpenReadWrite  (1362   ),  fmOpenRead  (1362   )  or  fmOpenWrite  (1362   ),  to  open  a  file  so
other processes can read/write the file as well.


fmShareDenyRead  =  $0030


fmOpenShareExclusive  is  used  in  the  FileOpen  (1422   )  call  OR-ed  together  with  one  of
fmOpenReadWrite  (1362   ),  fmOpenRead  (1362   )  or  fmOpenWrite  (1362   ),  to  open  a  file  so
other processes cannot read from it.


fmShareDenyWrite  =  $0020


fmOpenShareExclusive  is  used  in  the  FileOpen  (1422   )  call  OR-ed  together  with  one  of
fmOpenReadWrite (1362   ),  fmOpenRead (1362   ) or fmOpenWrite (1362   ),  to open a file ex-
clusively.


fmShareExclusive  =  $0010


fmOpenShareExclusive  is  used  in  the  FileOpen  (1422   )  call  OR-ed  together  with  one  of
fmOpenReadWrite (1362   ),  fmOpenRead (1362   ) or fmOpenWrite (1362   ),  to open a file ex-
clusively.


fsFromBeginning  =  0


fsFromBeginning is used to indicate in the FileSeek (1424   ) call that a seek operation should
be started at the start of the file.


fsFromCurrent  =  1


fsFromBeginning is used to indicate in the FileSeek (1424   ) call that a seek operation should
be started at the current position in the file.


fsFromEnd  =  2


fsFromBeginning is used to indicate in the FileSeek (1424   ) call that a seek operation should
be started at the last position in the file.


HexDisplayPrefix  :  String  =  '$'


HexDisplayPrefix  is  used  by  the  formatting  routines  to  indicate  that  the  number  which
follows the prefix is in Hexadecimal notation.


HoursPerDay  =  24


Number of hours in a day.


JulianEpoch  =  TDateTime  (  -  2415018.5  )


Starting point of the Julian calendar


LeadBytes  :  Set  of  Char  =  []



                                                                1363

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
LeadBytes contains the set of bytes that serve as lead byte in a MBCS string.


MaxCurrency  :  Currency  =  922337203685477.0000


Maximum currency value


MaxDateTime  :  TDateTime  =  2958465.99999


Maximum TDateTime value.


MAX_PATH  =  MaxPathLen


MAX_PATH is the maximum number of characters that a filename (including path) can contain
on the current operating system.


MinCurrency  :  Currency  =  -922337203685477.0000


Minimum Currency value


MinDateTime  :  TDateTime  =  -693593.0


Minimum TDateTime value.


MinsPerDay  =  HoursPerDay  *  MinsPerHour


Number of minutes per day.


MinsPerHour  =  60


Number of minutes per hour.


MonthDays  :  Array[Boolean]  of  TDayTable  =  (  (  31,28,31,30,31,30,31,31,30,31,30,31  )  ,  (  31,29,31,30,31,30,31,31,30,31,3*
 *0,31  )  )


Array with number of days in the months for leap and non-leap years.


MSecsPerDay  =  SecsPerDay  *  MSecsPerSec


Number of milliseconds per day


MSecsPerSec  =  1000


Number of milliseconds per second


NullStr  :  PString  =  @EmptyStr


Pointer to an empty string


PathDelim  =  DirectorySeparator


PathDelim refers to the system unit's DirectorySeparator constant, it is for Delphi com-
patibility only.



                                                                1364

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
PathSep  =  PathSeparator


PathSep refers to the system unit's PathSeparator constant, it is for Delphi compatibility
only.


pfBCB4Produced  =  $08000000


Not used in Free Pascal.


pfDelphi4Produced  =  $0C000000


Not used in Free Pascal.


pfDesignOnly  =  $00000002


Package is a design-time only package


pfExeModule  =  $00000000


Package is an executable


pfIgnoreDupUnits  =  $00000008


Ignore duplicate units in package


pfLibraryModule  =  $80000000


Package is a library


pfModuleTypeMask  =  $C0000000


Mask for module type flags


pfNeverBuild  =  $00000001


Never-build flag was specified when compiling package


pfPackageModule  =  $40000000


Package is a real package (not exe)


pfProducerMask  =  $0C000000


Mask for producer flags


pfProducerUndefined  =  $04000000


Not used in Free Pascal.


pfRunOnly  =  $00000004



                                                                1365

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
Package is a run-time only package


pfV3Produced  =  $00000000


Not used in Free Pascal.


RTL_SIGBUS  =  4


Bus error signal number (Unix only)


RTL_SIGDEFAULT  =  -1


Default signal handler (Unix only)


RTL_SIGFPE  =  1


Floating Point Error signal number (Unix only)


RTL_SIGILL  =  3


Illegal instruction signal number (Unix only)


RTL_SIGINT  =  0


INTERRUPT signal number (Unix only)


RTL_SIGLAST  =  RTL_SIGQUIT


Last signal number (Unix only)


RTL_SIGQUIT  =  5


QUIT signal number (Unix only)


RTL_SIGSEGV  =  2


Segmentation fault signal number (Unix only)


SecsPerDay  =  MinsPerDay  *  SecsPerMin


Number of seconds per day


SecsPerMin  =  60


Number of seconds per minute


SwitchChars  =  ['-']


The  characters  in  this  set  will  be  used  by  the  FindCmdLineSwitch  (1426   )  function  to  de-
termine whether a command-line argument is a switch (an option) or a value.  If the first
character of an argument is in SwitchChars, it will be considered an option or switch.



                                                                1366

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
SysConfigDir  :  String  =  ''


SysConfigDir is the default system configuration directory.  It is set at application startup
by the sysutils initialization routines.

This directory may be returned by the GetAppConfigDir (1443   ) call on some systems.


TextRecBufSize  =  256


Buffer size of text file record.


TextRecNameLength  =  256


Length of text file record filename field


ufImplicitUnit  =  $10


Unit was implicitly imported into package (did not appear in package contains list)


ufMainUnit  =  $01


Unit is the main unit of the package


ufOrgWeakUnit  =  $08


Unit is the original weak packaged unit


ufPackageUnit  =  $02


Unit is a packaged unit (appeared in package contains list)


ufWeakPackageUnit  =  ufPackageUnit  or  ufWeakUnit


Weak (original or not) packaged unit


ufWeakUnit  =  $04


Unit is a weak packaged unit


UnixDateDelta  =  Trunc  (  UnixEpoch  )


Number of days between 1.1.1900 and 1.1.1970


UnixEpoch  =  JulianEpoch  +  TDateTime  (  2440587.5  )


Starting point of the unix calendar (1/1/1970)



                                                                1367

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.11.2          Types

EHeapException  =  EHeapMemoryError


EHeapMemoryError is raised when an error occurs in the heap management routines.


ExceptClass  =  Class  of  Exception


ExceptClass is a Exception (1505   ) class reference.


FileRec  =  packed  record
    Handle  :  THandle;
    Mode  :  LongInt;
    RecSize  :  SizeInt;
    _private  :  Array[1..3*SizeOf(SizeInt)+5*SizeOf(pointer)]  of  Byte;
    UserData  :  Array[1..32]  of  Byte;
    name  :  Array[0..filerecnamelength]  of  Char;
end
FileRec describes a untyped file.  This record is made available so it can be used to implement
drivers for other than the normal file system file records.


Int64Rec  =  packed  record
end
Int64Rec can be used to extract the parts of a Int64:  the high and low cardinal, or a zero-
based array of 4 words, or a zero based array of 8 bytes.  Note that the meaning of the High
and Low parts are different on various CPUs.


LongRec  =  packed  record
end
LongRec can be used to extract the parts of an long Integer:  the high and low word, or the 4
separate bytes as a zero-based array of bytes.  Note that the meaning of High and Low parts
are different on various CPUs.


PByteArray  =  ^TByteArray


Generic pointer to TByteArray (1369   ).  Use to access memory regions as a byte array.


PDayTable  =  ^TDayTable


Pointer to TDayTable type.


PString  =  ^String


Pointer to a ansistring


PSysCharSet  =  ^TSysCharSet



                                                                1368

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
Pointer to TSysCharSet (1373   ) type.


PWordarray  =  ^TWordArray


Generic pointer to TWordArray (1373   ).  Use to access memory regions as a word array.


TByteArray  =  Array[0..32767]  of  Byte


TByteArray is a generic array definition, mostly for use as a base type of the PByteArray
(1368   ) type.


TCreateGUIDFunc  =  function(out  GUID:  TGUID)  :  Integer


TCreateGUIDFunc is the prototype for a GUID creation handler.  On return, the GUID argu-
ment should contain a new (unique) GUID. The return value of the function should be zero
for success, nonzero for failure.


TDayTable  =  Array[1..12]  of  Word


Array of day names.


TextBuf  =  Array[0..TextRecBufSize-1]  of  Char


TextBuf is the type for the default buffer in TextRec (1369   )


TextRec  =  packed  record
   Handle  :  THandle;
   Mode  :  LongInt;
   bufsize  :  SizeInt;
   _private  :  SizeInt;
   bufpos  :  SizeInt;
   bufend  :  SizeInt;
   bufptr  :  ^TextBuf;
   openfunc  :  pointer;
   inoutfunc  :  pointer;
   flushfunc  :  pointer;
   closefunc  :  pointer;
   UserData  :  Array[1..32]  of  Byte;
   name  :  Array[0..textrecnamelength-1]  of  Char;
   LineEnd  :  TLineEndStr;
   buffer  :  TextBuf;
end
TextRec describes a text file.  This record is made available so it can be used to implement
drivers for other than the normal file system file records.

To implement a driver, an Assign procedure must be implemented, which fills in the various
fields  of  the  record.   Most  notably,  the  callback  functions  must  be  filled  in  appropriately.
After this, the normal file operations will handle all necessary calls to the various callbacks.


TFilename  =  String



                                                                1369

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
TFileName is used in the TSearchRec (1372   ) definition.


TFileRec  =  FileRec


Alias for FileRec (1368   ) for Delphi compatibility.


TFloatFormat  =  (ffGeneral,ffExponent,ffFixed,ffNumber,ffCurrency)
                         Table 30.8:  Enumeration values for type TFloatFormat


                     _Value______________Explanation_______________________________________________________
                       ffCurrency         Monetary format.
                       ffExponent         Scientific format.
                       ffFixed            Fixed point format.
                       ffGeneral          General number format.
                       ffNumber           Fixed point format with thousand separatord
TFloatFormat is used to determine how a float value should be formatted in the FloatToText
(1432   ) function.


TFloatRec  =  record
   Exponent  :  Integer;
   Negative  :  Boolean;
   Digits  :  Array[0..18]  of  Char;
end
TFloatRec is used to descibe a floating point value by the FloatToDecimal (1428   ) function.


TFloatValue  =  (fvExtended,fvCurrency,fvSingle,fvReal,fvDouble,fvComp)
                          Table 30.9:  Enumeration values for type TFloatValue


                                         __Value______________Explanation_____________
                                           fvComp              Comp value
                                           fvCurrency          Currency value
                                           fvDouble            Double value
                                           fvExtended          Extended value
                                           fvReal              Real value
                                           fvSingle            Single value
TFloatValue determines which kind of value should be returned in the (untyped) buffer used
by the TextToFloat (1487   ) function.


TFormatSettings  =  record
   CurrencyFormat  :  Byte;
   NegCurrFormat  :  Byte;
   ThousandSeparator  :  Char;
   DecimalSeparator  :  Char;



                                                                1370

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
   CurrencyDecimals  :  Byte;
   DateSeparator  :  Char;
   TimeSeparator  :  Char;
   ListSeparator  :  Char;
   CurrencyString  :  String;
   ShortDateFormat  :  String;
   LongDateFormat  :  String;
   TimeAMString  :  String;
   TimePMString  :  String;
   ShortTimeFormat  :  String;
   LongTimeFormat  :  String;
   ShortMonthNames  :  TMonthNameArray;
   LongMonthNames  :  TMonthNameArray;
   ShortDayNames  :  TWeekNameArray;
   LongDayNames  :  TWeekNameArray;
   TwoDigitYearCenturyWindow  :  Word;
end
TFormatSettings is a record that contains a copy of all variables which determine formatting
in the various string formatting routines.  It is used to pass local copies of these values to
the various formatting routines in a thread-safe way.


TGetAppNameEvent  =  function  :  String


This  callback  type  is  used  by  the  OnGetApplicationName  (1375   )  to  return  an  alternative
application name.


TGetTempDirEvent  =  function(Global:  Boolean)  :  String


Function prototype for OnGetTempDir (1375   ) handler.


TGetTempFileEvent  =  function(const  Dir:  String;const  Prefix:  String)
                                                 :  String


Function prototype for OnGetTempFile (1376   ) handler.


TGetVendorNameEvent  =  function  :  String


TGetVendorNameEvent is the function prototype for the OnGetVendorName (1376   ) callback,
used by the VendorName (1496   ) function.


THandle  =  System.THandle


THandle refers to the definition of THandle in the system unit, and is provided for backward
compatibility only.


TIntegerSet  =  Set  of


TIntegerSet is a generic integer subrange set definition whose size fits in a single integer.


TLineEndStr  =



                                                                1371

               _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________

                                     Table 30.10:  Enumeration values for type TMbcsByteType


                                                     __Value_________________Explanation________________
                                                       mbLeadByte             Uses lead-byte
                                                       mbSingleByte           Single bytes
                                                       mbTrailByte            Uses trailing byte

               TLineEndStr is used in the TextRec (1369   ) record to indicate the end-of-line sequence for a
               text file.


               TMbcsByteType  =  (mbSingleByte,mbLeadByte,mbTrailByte)


               Type of multi-byte character set.


               TMonthNameArray  =  Array[1..12]  of  String


               TMonthNameArray is used in the month long and short name arrays.


               TProcedure  =  procedure


               TProcedure is a general definition of a procedural callback.


               TReplaceFlags=  Set  of  (rfReplaceAll,rfIgnoreCase)


               TReplaceFlags determines the behaviour of the StringReplace (1469   ) function.


               TSearchRec  =  record
                  Time  :  LongInt;
                  Size  :  Int64;
                  Attr  :  LongInt;
                  Name  :  TFilename;
                  ExcludeAttr  :  LongInt;
                  FindHandle  :  Pointer;
                  Mode  :  TMode;
                  PathOnly  :  AnsiString;
               end
               TSearchRec  is  a  search  handle  description  record.   It  is  initialized  by  a  call  to  FindFirst
               (1426   ) and can be used to do subsequent calls to FindNext (1427   ).  It contains the result of
               these function calls.  It must be used to close the search sequence with a call to FindClose
               (1426   ).

Remark:         Not  all  fields  of  this  record  should  be  used.  Some  of  the  fields  are  for  internal  use  only.
               (PathOnly for example, is only provided for Kylix compatibility)


               TSignalState  =  (ssNotHooked,ssHooked,ssOverridden)


               TSignalState indicates the state of a signal handler in a unix system for a particular signal.


               TSysCharSet  =  Set  of  Char



                                                                               1372

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___

                         Table 30.11:  Enumeration values for type TSignalState


                        __Value_________________Explanation____________________________________________
                          ssHooked              A signal handler is set for the signal.
                          ssNotHooked           No signal handler is set for the signal.
                          ssOverridden          A signal handler was set for the signal
Generic set of characters type.


TSysLocale  =  record
   DefaultLCID  :  Integer;
   PriLangID  :  Integer;
   SubLangID  :  Integer;
end
TSysLocale describes the current locale.  If Fareast or MBCS is True, then the current locale
uses a Multi-Byte Character Set.  If  MiddleEast or RightToLeft is True then words and
sentences are read from right to left.


TTerminateProc  =  function  :  Boolean


TTerminateProc is the procedural type which should be used when adding exit procedures.


TTextRec  =  TextRec


Alias for TextRec (1369   ) for Delphi compatibility.


TTimeStamp  =  record
   Time  :  Integer;
   Date  :  Integer;
end
TTimeStamp contains a timestamp, with the date and time parts specified as separate TDateTime
values.


TWeekNameArray  =  Array[1..7]  of  String


TWeekNameArray is used in the day long and short name arrays.


TWordArray  =  Array[0..16383]  of  Word


TWordArray is a generic array definition, mostly for use as a base type of the PWordArray
(1369   ) type.


WordRec  =  packed  record
   Lo  :  Byte;
   Hi  :  Byte;
end
LongRec can be used to extract the parts of a word:  the high and low byte.  Note that the
meaning of the High and Low parts are different on various CPUs.



                                                                1373

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.11.3          Variables

CurrencyDecimals  :  Byte


CurrencyDecimals is the number of decimals to be used when formatting a currency.  It is
used by the float formatting routines.  The initialization routines of the SysUtils unit initialize
this string with a value conforming to the regional preferences of the user or system regional
default.


CurrencyFormat  :  Byte


CurrencyFormat is the default format string for positive currencies.  It is used by the float
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


CurrencyString  :  String


CurrencyString is the currency symbol for the current locale.  It is used by the float for-
matting routines.  The initialization routines of the SysUtils unit initialize this string with a
value conforming to the regional preferences of the user or system regional default.


DateSeparator  :  Char


DateSeparator is the character used by various date/time conversion routines as the char-
acter that separates the day from the month and the month from the year in a date notation.
It  is  used  by  the  date  formatting  routines.  The  initialization  routines  of  the  SysUtils  unit
initialize this string with a value conforming to the regional preferences of the user or system
regional default.


DecimalSeparator  :  Char


DecimalSeparator is used to display the decimal symbol in floating point numbers or cur-
rencies.  It is used by the float formatting routines.  The initialization routines of the SysUtils
unit initialize this string with a value conforming to the regional preferences of the user or
system regional default.


DefaultFormatSettings  :  TFormatSettings  =  (CurrencyFormat:1;NegCurrFormat:5;ThousandSeparator:',';DecimalSeparator:'.';Currency*
 *Decimals:2;DateSeparator:'-';TimeSeparator:':';ListSeparator:',';CurrencyString:'$';ShortDateFormat:'d/m/y';LongDateFormat:'dd"  *
 *"mmmm"  "yyyy';TimeAMString:'AM';TimePMString:'PM';ShortTimeFormat:'hh:nn';LongTimeFo@


DefaultFormatSettings contains the default settings for all type of formatting constants.
If no thread-specific values are specified when a formatting function is called, this record is
used as a default.

All other formatting constants refer to the fields of this variable using absolute addressing.


FalseBoolStrs  :  Array  of  String


FalseBoolStrs contains the strings that will result in a False return value by StrToBool
(1477   ).


ListSeparator  :  Char


ListSeparator is the character used in lists of values.  It is locale dependent.
                                                                1374

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
LongDateFormat  :  String


LongDateFormat contains a template to format a date in a long format.  It is used by the
date formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


LongDayNames  :  TWeekNameArray


LongDayNames  is  an  array  with  the  full  names  of  days.  It  is  used  by  the  date  formatting
routines.  The  initialization  routines  of  the  SysUtils  unit  initialize  this  string  with  a  value
conforming to the regional preferences of the user or system regional default.


LongMonthNames  :  TMonthNameArray


LongMonthNames is an array with the full names of months.  It is used by the date formatting
routines.  The  initialization  routines  of  the  SysUtils  unit  initialize  this  string  with  a  value
conforming to the regional preferences of the user or system regional default.


LongTimeFormat  :  String


LongTimeFormat  contains  a  template  to  format  a  time  in  full  notation.  It  is  used  by  the
time formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


NegCurrFormat  :  Byte


CurrencyFormat is the default format string for negative currencies.  It is used by the float
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


OnCreateGUID  :  TCreateGUIDFunc  =  nil


OnCreateGUID can be set to point to a custom routine that creates GUID values.  If set, the
CreateGUID (1399   ) function will use it to obtain a GUID value.  If it is not set, a default
implementation using random values will be used to create the unique value.  The function
should return a valid GUID in the GUID parameter, and should return zero in case of success.


OnGetApplicationName  :  TGetAppNameEvent


By default,  the configuration file routines GetAppConfigDir (1443   ) and GetAppConfigFile
(1443   )  use  a  default  application  name  to  construct  a  directory  or  filename.  This  callback
can be used to provide an alternative application name.

Since the result of this callback will be used to construct a filename, care should be taken
that the returned name does not contain directory separator characters or characters that
cannot appear in a filename.


OnGetTempDir  :  TGetTempDirEvent


OnGetTempDir can be used to provide custom behaviour for the GetTempDir (1447   ) function.
Note that the returned name should have a trailing directory delimiter character.


OnGetTempFile  :  TGetTempFileEvent



                                                                1375

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
OnGetTempDir can be used to provide custom behaviour for the GetTempFileName (1448   )
function.  Note that the values for Prefix and Dir should be observed.


OnGetVendorName  :  TGetVendorNameEvent


OnGetVendorName is the callback used by the VendorName (1496   ) function.  It should be set
to a handler that returns the vendor of the application.


OnShowException  :  procedure(Msg:  ShortString)


OnShowException is the callback that ShowException (1462   ) uses to display a message in
a GUI application.  For GUI applications, this variable should always be set.  Note that no
memory may be available when this callback is called, so the callback should already have
all resources it needs, when the callback is set.


ShortDateFormat  :  String


ShortDateFormat contains a template to format a date in a short format.  It is used by the
date formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


ShortDayNames  :  TWeekNameArray


ShortDayNames  is  an  array  with  the  abbreviated  names  of  days.   It  is  used  by  the  date
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


ShortMonthNames  :  TMonthNameArray


ShortMonthNames is an array with the abbreviated names of months.  It is used by the date
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


ShortTimeFormat  :  String


ShortTimeFormat contains a template to format a time in a short notation.  It is used by the
time formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


SysLocale  :  TSysLocale


SysLocale is initialized by the initialization code of the SysUtils unit.  For an explanation of
the fields, see TSysLocale (1373   )


ThousandSeparator  :  Char


ThousandSeparator  is  used  to  separate  groups  of  thousands  in  floating  point  numbers  or
currencies.   It  is  used  by  the  float  formatting  routines.   The  initialization  routines  of  the
SysUtils unit initialize this string with a value conforming to the regional preferences of the
user or system regional default.


TimeAMString  :  String



                                                                1376

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                TimeAMString is used to display the AM symbol in the time formatting routines.  It is used
                by  the  time  formatting  routines.   The  initialization  routines  of  the  SysUtils  unit  initialize
                this string with a value conforming to the regional preferences of the user or system regional
                default.


                TimePMString  :  String


                TimePMString is used to display the PM symbol in the time formatting routines.  It is used
                by  the  time  formatting  routines.   The  initialization  routines  of  the  SysUtils  unit  initialize
                this string with a value conforming to the regional preferences of the user or system regional
                default.


                TimeSeparator  :  Char


                TimeSeparator  is  used  by  the  time  formatting  routines  to  separate  the  hours  from  the
                minutes and the minutes from the seconds.  It is used by the time formatting routines.  The
                initialization routines of the SysUtils unit initialize this string with a value conforming to the
                regional preferences of the user or system regional default.


                TrueBoolStrs  :  Array  of  String


                TrueBoolStrs  contains  the  strings  that  will  result  in  a  True  return  value  by  StrToBool
                (1477   ).


                TwoDigitYearCenturyWindow  :  Word


                Window to determine what century 2 digit years are in.
                30.12            Procedures  and  functions



                30.12.1          AbandonSignalHandler

    Synopsis:

Declaration:     procedure  AbandonSignalHandler(RtlSigNum:  Integer)

    Visibility:   default

Description:     This function is declared for Kylix compatibility, but is not implemented.
                30.12.2          Abort

    Synopsis:    Abort program execution.

Declaration:     procedure  Abort

    Visibility:   default

Description:     Abort raises an EAbort (1499   ) exception.

    See also:    Abort (1377   )



                                                                                1377

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.3          AddDisk

    Synopsis:    Add a disk to the list of known disks (Unix only)

Declaration:     function  AddDisk(const  path:  String)  :  Byte

    Visibility:   default

Description:     On Unix-like platforms both the DiskFree (1408   ) and DiskSize (1408   ) 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 (1408   ), DiskSize (1408   )
                30.12.4          AddTerminateProc

    Synopsis:    Add a procedure to the exit chain.

Declaration:     procedure  AddTerminateProc(TermProc:  TTerminateProc)

    Visibility:   default

Description:     AddTerminateProc adds TermProc to the list of exit procedures.  When the program exits,
                the list of exit procedures is run over, and all procedures are called one by one, in the reverse
                order that they were added to the exit chain.

       Errors:   If no memory is available on the heap, an exception may be raised.

    See also:    TTerminateProc (1373   ), CallTerminateProcs (1395   )
                30.12.5          AdjustLineBreaks

    Synopsis:    Convert possible line-endings to the currently valid line ending.

Declaration:     function  AdjustLineBreaks(const  S:  String)  :  String
                function  AdjustLineBreaks(const  S:  String;Style:  TTextLineBreakStyle)
                                                           :  String

    Visibility:   default

Description:     AdjustLineBreaks will change all #13 characters with #13#10 on Windowsnt and dos.  On
                Unix-like platforms, all #13#10 character pairs are converted to #10 and single #13 characters
                also.

       Errors:   None.

                                                                                1378

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    See also:    AnsiCompareStr (1379   ), AnsiCompareText (1380   )


                Listing:  ./sysutex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   T h i s  p r o g r a m 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 k sf u 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 dand   '+
                            #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___.____________________________________________________________________________________________________________*
 *___________

                30.12.6          AnsiCompareFileName

    Synopsis:    Compare 2 filenames.

Declaration:     function  AnsiCompareFileName(const  S1:  String;const  S2:  String)
                                                                :  SizeInt

    Visibility:   default

Description:     AnsiCompareFileName compares 2 filenames S1 and S2, and returns


                < 0 if  S1<S2.

                = 0   if  S1=S2.

                > 0  if  S1>S2.


                The function actually checks FileNameCaseSensitive and returns the result of AnsiCom-
                pareStr (1379   ) or AnsiCompareText (1380   ) depending on whether FileNameCaseSensitive
                is True or False

       Errors:   None.

    See also:    AnsiCompareStr (1379   ), AnsiCompareText (1380   ), AnsiLowerCaseFileName (1383   )
                30.12.7          AnsiCompareStr

    Synopsis:    Compare 2 ansistrings, case sensitive, ignoring accents characters.

Declaration:     function  AnsiCompareStr(const  S1:  String;const  S2:  String)  :  Integer

    Visibility:   default

Description:     AnsiCompareStr compares two strings and returns the following result:


                < 0 if  S1<S2.

                0 if  S1=S2.

                > 0  if  S1>S2.

                                                                                1379

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                The  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                characters.  Contrary to AnsiCompareText (1380   ), the comparision is case sensitive.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AdjustLineBreaks (1378   ), AnsiCompareText (1380   )


                Listing:  ./sysutex/ex49.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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 := 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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.8          AnsiCompareText

    Synopsis:    Compare 2 ansistrings, case insensitive, ignoring accents characters.

Declaration:     function  AnsiCompareText(const  S1:  String;const  S2:  String)  :  Integer

    Visibility:   default

Description:     AnsiCompareText compares two strings and returns the following result:


                <0 if  S1<S2.

                0 if  S1=S2.

                >0  if  S1>S2.



                                                                                1380

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                the  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                characters.  Contrary to AnsiCompareStr (1379   ), the comparision is case insensitive.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AdjustLineBreaks (1378   ), AnsiCompareText (1380   )


                Listing:  ./sysutex/ex50.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.9          AnsiDequotedStr

    Synopsis:

Declaration:     function  AnsiDequotedStr(const  S:  String;AQuote:  Char)  :  String

    Visibility:   default

Description:

       Errors:
                30.12.10           AnsiExtractQuotedStr

    Synopsis:    Removes the first quoted string from a string.
                                                                                1381

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Declaration:     function  AnsiExtractQuotedStr(var  Src:  PChar;Quote:  Char)  :  String

    Visibility:  default

Description:     AnsiExtractQuotedStr returns the first quoted string in Src, and deletes the result from
                Src.  The resulting string has with Quote characters removed from the beginning and end
                of the string (if they are present), and double Quote characters replaced by a single Quote
                characters.  As such, it revereses the action of AnsiQuotedStr (1384   ).

       Errors:   None.

    See also:    AnsiQuotedStr (1384   )


                Listing:  ./sysutex/ex51.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 1;


                {   T h i s  p r o g r a m 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(rP c h a r(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(tPrc h a r(S ) , '" ' ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.11           AnsiLastChar

    Synopsis:    Return a pointer to the last character of a string.

Declaration:     function  AnsiLastChar(const  S:  String)  :  PChar

    Visibility:   default

Description:     This function returns a pointer to the last character of  S.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.  If none is installed, this function is the same as @S[Length[S]].

       Errors:   None.

    See also:    AnsiStrLastChar (1386   )


                Listing:  ./sysutex/ex52.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 2;


                {   T h i s  p r o g r a m 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


                Var    S   :   A n s i S t r i n;g
                       L   :   L o n g i n t;


                Begin



                                                                                1382

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                    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 a(rS) ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.12           AnsiLowerCase

    Synopsis:    Return a lowercase version of a string.

Declaration:     function  AnsiLowerCase(const  s:  String)  :  String

    Visibility:   default

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:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiUpperCase (1391   ), AnsiStrLower (1389   ), AnsiStrUpper (1390   )


                Listing:__./sysutex/ex53.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 3;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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     m i x e d S T r i n g' ) ;
                    T e s t i t( 'a   l o w e r c a s es t r i n g') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.13           AnsiLowerCaseFileName

    Synopsis:    Convert filename to lowercase.

Declaration:     function  AnsiLowerCaseFileName(const  s:  String)  :  String

    Visibility:   default

Description:     AnsiLowerCaseFileName simply returns the result of


                AnsiLowerCase(S);


    See also:    AnsiLowerCase (1383   ), AnsiCompareFileName (1379   ), AnsiUpperCaseFileName (1391   )



                                                                                1383

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.14           AnsiPos

    Synopsis:    Return Position of one ansistring in another.

Declaration:     function  AnsiPos(const  substr:  String;const  s:  String)  :  SizeInt

    Visibility:   default

Description:     AnsiPos does the same as the standard Pos function.

    See also:    AnsiStrPos (1389   ), AnsiStrScan (1390   ), AnsiStrRScan (1390   )
                30.12.15           AnsiQuotedStr

    Synopsis:    Return a quoted version of a string.

Declaration:     function  AnsiQuotedStr(const  S:  String;Quote:  Char)  :  String

    Visibility:   default

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 (1381   ).

                For an example, see AnsiExtractQuotedStr (1381   )

       Errors:   None.

    See also:    AnsiExtractQuotedStr (1381   )
                30.12.16           AnsiSameStr

    Synopsis:    Checks whether 2 strings are the same (case sensitive)

Declaration:     function  AnsiSameStr(const  s1:  String;const  s2:  String)  :  Boolean

    Visibility:   default

Description:     SameText calls AnsiCompareStr (1379   ) with S1 and S2 as parameters and returns True if
                the result of that call is zero, or False otherwise.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiCompareStr (1379   ), SameText (1461   ), AnsiSameText (1384   )
                30.12.17           AnsiSameText

    Synopsis:    Checks whether 2 strings are the same (case insensitive)

Declaration:     function  AnsiSameText(const  s1:  String;const  s2:  String)  :  Boolean

    Visibility:   default

Description:     SameText calls AnsiCompareText (1380   ) with S1 and S2 as parameters and returns True if
                the result of that call is zero, or False otherwise.

       Errors:

    See also:    AnsiCompareText (1380   ), SameText (1461   ), AnsiSameStr (1384   )



                                                                                1384

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.18           AnsiStrComp

    Synopsis:    Compare two null-terminated strings.  Case sensitive.

Declaration:     function  AnsiStrComp(S1:  PChar;S2:  PChar)  :  Integer

    Visibility:   default

Description:     AnsiStrComp compares 2 PChar strings, and returns the following result:


                <0 if  S1<S2.

                0 if  S1=S2.

                >0  if  S1>S2.


                The comparision of the two strings is case-sensitive.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiCompareText (1380   ), AnsiCompareStr (1379   )


                Listing:  ./sysutex/ex54.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e A n s i S t r C o m pf u n c t i o n }


                Uses      s y s u t i l;s


                 P r o c e d u r eT e s t I t ( S1  ,S2    :  P c h a r) ;


                Var    R   :   L o n g i n t;


                 b e g i n
                    R := A n s i S t r 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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.19           AnsiStrIComp

    Synopsis:    Compare two null-terminated strings.  Case insensitive.
                                                                                1385

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Declaration:     function  AnsiStrIComp(S1:  PChar;S2:  PChar)  :  Integer

    Visibility:  default

Description:     AnsiStrIComp 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-insensitive.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiCompareText (1380   ), AnsiCompareStr (1379   )


                Listing:  ./sysutex/ex55.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 5;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT e s t I t ( S1  ,S2    :  P c h a r) ;


                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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.20           AnsiStrLastChar

    Synopsis:    Return a pointer to the last character of a string.

Declaration:     function  AnsiStrLastChar(Str:  PChar)  :  PChar

    Visibility:   default
                                                                                1386

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     Return a pointer to the last character of the null-terminated string.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.  If none is installed, this function is the same as @S[Length[S]].

       Errors:   None.

    See also:    AnsiCompareText (1380   ), AnsiCompareStr (1379   )


                Listing:  ./sysutex/ex56.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e A n s i S t r L C o m pf u n c t i o n }


                Uses      s y s u t i l;s


                 P r o c e d u r eT e s t I t ( S1  ,S2    :  P c h a r;  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 C o m(pS1  ,S2  ,L ) ;
                    Write     (  'F i r s t  ' ,L , '  c h a r a c t e r so 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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.21           AnsiStrLComp

    Synopsis:    Compare a limited number of characters of 2 strings

Declaration:     function  AnsiStrLComp(S1:  PChar;S2:  PChar;MaxLen:  cardinal)  :  Integer

    Visibility:   default

Description:     AnsiStrLComp functions the same as AnsiStrComp (1385   ),  but compares at most MaxLen
                characters.  If the first MaxLen characters in both strings are the same, then zero is returned.

                Note that this function processes embedded null characters, treating them as a normal char-
                acter.

       Errors:   None.

    See also:    AnsiStrComp (1385   ), AnsiStrIComp (1385   ), AnsiStrLIComp (1388   )


                                                                                1387

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.22           AnsiStrLIComp

    Synopsis:    Compares a given number of characters of a string, case insensitive.

Declaration:     function  AnsiStrLIComp(S1:  PChar;S2:  PChar;MaxLen:  cardinal)  :  Integer

    Visibility:   default

Description:     AnsiStrLIComp  compares  the  first  Maxlen  characters  of  2  PChar  strings,  S1  and  S2,  and
                returns the following result:


                <0 if  S1<S2.

                0 if  S1=S2.

                >0  if  S1>S2.


                The comparision of the two strings is case-insensitive.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiCompareText (1380   ), AnsiCompareStr (1379   )


                Listing:  ./sysutex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 7;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT e s t I t ( S1  ,S2    :  P c h a r;  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 so 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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________
                                                                                1388

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.23           AnsiStrLower

    Synopsis:    Convert a null-terminated string to all-lowercase characters.

Declaration:     function  AnsiStrLower(Str:  PChar)  :  PChar

    Visibility:   default

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 (1383   ).
                It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so  special
                characters are converted correctly as well.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiStrUpper (1390   ), AnsiLowerCase (1383   )


                Listing:  ./sysutex/ex59.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 9;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT e s t i t ( S   :  P c h a r) ;


                 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     m i x e d S T r i n g' ) ;
                    T e s t i t( 'a   l o w e r c a s es t r i n g') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.24           AnsiStrPos

    Synopsis:    Return position of one null-terminated substring in another

Declaration:     function  AnsiStrPos(str:  PChar;substr:  PChar)  :  PChar

    Visibility:   default

Description:     AnsiStrPos returns a pointer to the first occurrence of  SubStr in Str.  If  SubStr does not
                occur in Str then Nil is returned.

       Errors:   An access violation may occur if either Str or SubStr point to invalid memory.

    See also:    AnsiPos (1384   ), AnsiStrScan (1390   ), AnsiStrRScan (1390   )
                                                                                1389

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.25           AnsiStrRScan

    Synopsis:    Find last occurrence of a character in a null-terminated string.

Declaration:     function  AnsiStrRScan(Str:  PChar;Chr:  Char)  :  PChar

    Visibility:   default

Description:     AnsiStrPos  returns  a  pointer  to  the  last  occurrence  of  the  character  Chr  in  Str.  If  Chr
                does not occur in Str then Nil is returned.

       Errors:   An access violation may occur if  Str points to invalid memory.

    See also:    AnsiPos (1384   ), AnsiStrScan (1390   ), AnsiStrPos (1389   )
                30.12.26           AnsiStrScan

    Synopsis:    Find first occurrence of a character in a null-terminated string.

Declaration:     function  AnsiStrScan(Str:  PChar;Chr:  Char)  :  PChar

    Visibility:   default

Description:     AnsiStrPos returns a pointer to the first  occurrence of the character Chr in Str.  If  Chr
                does not occur in Str then Nil is returned.

       Errors:   An access violation may occur if  Str points to invalid memory.

    See also:    AnsiPos (1384   ), AnsiStrScan (1390   ), AnsiStrPos (1389   )
                30.12.27           AnsiStrUpper

    Synopsis:    Convert a null-terminated string to all-uppercase characters.

Declaration:     function  AnsiStrUpper(Str:  PChar)  :  PChar

    Visibility:   default

Description:     AnsiStrUpper  converts  the  PCharStr  to  uppercase  characters  and  returns  the  resulting
                string.  Note that Str itself is modified, not a copy, as in the case of AnsiUpperCase (1391   ).
                It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so  special
                characters are converted correctly as well.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiUpperCase (1391   ), AnsiStrLower (1389   ), AnsiLowerCase (1383   )


                Listing:  ./sysutex/ex60.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 0;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT e s t i t ( S   :  P c h a r) ;

                                                                                1390

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                 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     m i x e d S T r i n g' ) ;
                    T e s t i t( 'a   l o w e r c a s es t r i n g') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.28           AnsiUpperCase

    Synopsis:    Return an uppercase version of a string, taking into account special characters.

Declaration:     function  AnsiUpperCase(const  s:  String)  :  String

    Visibility:   default

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
                special characters are converted correctly as well.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.

       Errors:   None.

    See also:    AnsiStrUpper (1390   ), AnsiStrLower (1389   ), AnsiLowerCase (1383   )


                Listing:  ./sysutex/ex61.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 0;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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     m i x e d S T r i n g' ) ;
                    T e s t i t( 'a   l o w e r c a s es t r i n g') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.29           AnsiUpperCaseFileName

    Synopsis:    Convert filename to uppercase.

Declaration:     function  AnsiUpperCaseFileName(const  s:  String)  :  String

    Visibility:   default
                                                                                1391

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     AnsiUpperCaseFileName simply returns the result of


                AnsiUpperCase(S);


    See also:    AnsiUpperCase (1391   ), AnsiCompareFileName (1379   ), AnsiLowerCaseFileName (1383   )
                30.12.30           AppendStr

    Synopsis:    Append one ansistring to another.

Declaration:     procedure  AppendStr(var  Dest:  String;const  S:  String)

    Visibility:   default

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 (1393   ), NewStr (1456   ), DisposeStr (1409   )


                Listing:  ./sysutex/ex62.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e A p p e n d S t r 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 :=  '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___.____________________________________________________________________________________________________________*
 *___________

                30.12.31           ApplicationName

    Synopsis:    Return a default application name

Declaration:     function  ApplicationName  :  String

    Visibility:   default

Description:     ApplicationName  returns  the  name  of  the  current  application.  Standard  this  is  equal  to
                the result of ParamStr(0), but it can be customized by setting the OnGetApplicationName
                (1375   ) callback.

       Errors:   None.

    See also:    GetAppConfigDir (1443   ), OnGetApplicationName (1375   ), GetAppConfigFile (1443   ), Con-
                figExtension (1361   )



                                                                                1392

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.32           AssignStr

    Synopsis:    Assigns an ansistring to a null-terminated string.

Declaration:     procedure  AssignStr(var  P:  PString;const  S:  String)

    Visibility:   default

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 (1456   ), AppendStr (1392   ), DisposeStr (1409   )


                Listing:  ./sysutex/ex63.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e A s s i g n S t r f 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 r(P , 'A  S e c o n d  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 r(P) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.33           BCDToInt

    Synopsis:    Convert a BCD coded integer to a normal integer.

Declaration:     function  BCDToInt(Value:  Integer)  :  Integer

    Visibility:   default

Description:     BCDToInt converts a BCD coded integer to a normal integer.

       Errors:   None.

    See also:    StrToInt (1482   ), IntToStr (1451   )


                Listing:  ./sysutex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 4;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT e s t i t (  L   :   l o n g i n t) ;
                 b e g i n



                                                                                1393

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.34           Beep

    Synopsis:    Sound the system bell.

Declaration:     procedure  Beep

    Visibility:   default

Description:     Beep sounds the system bell, if one is available.

       Errors:   This routine may not be implemented on all platforms.
                30.12.35           BoolToStr

    Synopsis:    Convert a boolean value to a string.

Declaration:     function  BoolToStr(B:  Boolean;UseBoolStrs:  Boolean)  :  String

    Visibility:   default

Description:     BoolToStr converts the boolean B to one of the strings 'TRUE' or 'FALSE'

       Errors:   None.

    See also:    StrToBool (1477   )
                30.12.36           ByteToCharIndex

    Synopsis:    Convert a character index in Bytes to an Index in characters

Declaration:     function  ByteToCharIndex(const  S:  String;Index:  Integer)  :  Integer

    Visibility:   default

Description:     ByteToCharIndex returns the index (in characters) of the Index-th byte in S.

       Errors:   This function does not take into account MBCS yet.

    See also:    CharToByteLen (1396   ), ByteToCharLen (1394   )
                30.12.37           ByteToCharLen

    Synopsis:    Convert a length in bytes to a length in characters.

Declaration:     function  ByteToCharLen(const  S:  String;MaxLen:  Integer)  :  Integer

    Visibility:   default

Description:     ByteToCharLen returns the number of bytes in S, but limits the result to MaxLen



                                                                                1394

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
       Errors:   This function does not take into account MBCS yet.

    See also:    CharToByteLen (1396   ), ByteToCharIndex (1394   )
                30.12.38           ByteType

    Synopsis:    Return the type of byte in an ansistring for a multi-byte character set

Declaration:     function  ByteType(const  S:  String;Index:  Integer)  :  TMbcsByteType

    Visibility:   default

Description:     ByteType returns the type of byte in the ansistring S at (1-based) position Index.

       Errors:   No checking on the index is performed.

    See also:    TMbcsByteType (1372   ), StrByteType (1464   )
                30.12.39           CallTerminateProcs

    Synopsis:    Call the exit chain procedures.

Declaration:     function  CallTerminateProcs  :  Boolean

    Visibility:   default

Description:     CallTerminateProcs  is  run  on  program  exit.   It  executes  all  terminate  procedures  that
                were added to the exit chain with AddTerminateProc (1378   ), and does this in reverse order.

       Errors:   If  one  of  the  exit  procedure  raises  an  exception,  it  is  not  caught,  and  the  remaining  exit
                procedures will not be executed.

    See also:    TTerminateProc (1373   ), AddTerminateProc (1378   )
                30.12.40           ChangeFileExt

    Synopsis:    Change the extension of a filename.

Declaration:     function  ChangeFileExt(const  FileName:  String;const  Extension:  String)
                                                      :  String

    Visibility:   default

Description:     ChangeFileExt changes the file extension in FileName to Extension.  The extension Extension
                includes the starting .  (dot).  The previous extension of  FileName are all characters after
                the last ., the .  character included.

                If  FileName doesn't have an extension, Extension is just appended.

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExpandFileName (1413   )


                                                                                1395

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.41           CharToByteLen

    Synopsis:    Convert a length in characters to a length in bytes.

Declaration:     function  CharToByteLen(const  S:  String;MaxLen:  Integer)  :  Integer

    Visibility:   default

Description:     CharToByteLen returns the number of bytes in S, but limits the result to MaxLen

       Errors:   This function does not take into account MBCS yet.

    See also:    ByteToCharLen (1394   ), ByteToCharIndex (1394   )
                30.12.42           CompareMem

    Synopsis:    Compare two memory areas.

Declaration:     function  CompareMem(P1:  Pointer;P2:  Pointer;Length:  cardinal)  :  Boolean

    Visibility:   default

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:


                <0 if at some position the byte at P1 is less than the byte at the same postion at P2.

                0 if all L bytes are the same.

                >0  if at some position the byte at P1 is greater than the byte at the same postion at P2.


       Errors:
                30.12.43           CompareMemRange

    Synopsis:    Compare 2 memory locations

Declaration:     function  CompareMemRange(P1:  Pointer;P2:  Pointer;Length:  cardinal)
                                                         :  Integer

    Visibility:   default

Description:     CompareMemRange compares the 2 memory locations pointed to by P1 and P2 byte per byte.
                It stops comparing after Length bytes have been compared,  or when it has encountered 2
                different bytes.  The result is then


                >0  if a byte in range P1 was found that is bigger than the corresponding byte in range P2.

                0 if all bytes in range P1 are the same as the corresponding bytes in range P2.

                <0 if a byte in range P1 was found that is less than the corresponding byte in range P2.


       Errors:   None.

    See also:    SameText (1461   )



                                                                                1396

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.44           CompareStr

    Synopsis:    Compare 2 ansistrings case-sensitively, ignoring special characters.

Declaration:     function  CompareStr(const  S1:  String;const  S2:  String)  :  Integer
                                                ;    Overload

    Visibility:   default

Description:     CompareStr compares two strings, S1 and S2, and returns the following result:


                <0 if  S1<S2.

                0 if  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 (1380   ), AnsiCompareStr (1379   ), CompareText (1398   )


                Listing:  ./sysutex/ex65.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e C o m p a r e S t r f u n c t i o n}
                { $H + }


                Uses      s y s u t i l;s


                 P r o c e d u r eT 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 := C o m p a r e S t r(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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                                                                                1397

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.45           CompareText

    Synopsis:    Compare 2 ansistrings case insensitive.

Declaration:     function  CompareText(const  S1:  String;const  S2:  String)  :  Integer

    Visibility:   default

Description:     CompareText compares two strings, S1 and S2, and returns the following result:


                <0 if  S1<S2.

                0 if  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 (1380   ), AnsiCompareStr (1379   ), CompareStr (1397   )


                Listing:  ./sysutex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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 t o  ' )
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.46           ComposeDateTime

    Synopsis:    Add a date and time

Declaration:     function  ComposeDateTime(Date:  TDateTime;Time:  TDateTime)  :  TDateTime



                                                                                1398

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    Visibility:  default

Description:     ComposeDateTime correctly adds Date and Time, also for dates before 1899-12-31.  For dates
                after this date, it is just the mathematical addition.

       Errors:   None.

    See also:    EncodeDateTime (1356   )
                30.12.47           CreateDir

    Synopsis:    Create a new directory

Declaration:     function  CreateDir(const  NewDir:  String)  :  Boolean

    Visibility:   default

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 (1458   )


                Listing:  ./sysutex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e C r e a t e D i r and    RemoveDir        f u n c t i o n s}
                {   Run    t h i s  p r o g r a m 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    D i r e c t o r y 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 t o  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
                        I f  Not    RemoveDir        ( ' NewDir    ' )  Then
                           W r i t e l n ( ' F a i l e d t o  r e m o v e 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.48           CreateGUID

    Synopsis:    Create a new GUID

Declaration:     function  CreateGUID(out  GUID:  TGUID)  :  Integer

    Visibility:   default
                                                                                1399

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     CreateGUID can be called to create a new GUID (Globally Unique Identifier) value.  The
                function returns the new GUID value in GUID and returns zero in case the GUID was created
                succesfully.  If no GUID was created, a nonzero error code is returned.

                The default mechanism for creating a new GUID is system dependent.  If operating system
                support is available, it is used.  If none is available, a default implementation using random
                numbers is used.

                The OnCreateGUID callback can be set to hook a custom mechanism behind the CreateGUID
                function.  This can be used to lt the GUID be created by an external GUID creation library.

       Errors:   On error, a nonzero return value is returned.

    See also:    CreateGUID (1399   )
                30.12.49           CurrentYear

    Synopsis:    Return the current year

Declaration:     function  CurrentYear  :  Word

    Visibility:   default

Description:     CurrentYear returns the current year as a 4-digit number.

       Errors:   None.

    See also:    Date (1401   ), Time (1488   ), Now (1457   )
                30.12.50           CurrToStr

    Synopsis:    Convert a currency value to a string.

Declaration:     function  CurrToStr(Value:  Currency)  :  String

    Visibility:   default

Description:     CurrToStr  will  convert  a  currency  value  to  a  string  with  a  maximum  of  15  digits,  and
                precision 2.  Calling CurrToStr is equivalent to calling FloatToStrF (1430   ):


                FloatToStrF(Value,ffNumber,15,2);


       Errors:   None.

    See also:    FloatToStrF (1430   ), StrToCurr (1478   )
                30.12.51           CurrToStrF

    Synopsis:    Format a currency to a string

Declaration:     function  CurrToStrF(Value:  Currency;Format:  TFloatFormat;
                                                Digits:  Integer)  :  String
                function  CurrToStrF(Value:  Currency;Format:  TFloatFormat;
                                                Digits:  Integer;
                                                const  FormatSettings:  TFormatSettings)  :  String

    Visibility:   default
                                                                                1400

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     CurrToStrF formats the currency Value according to the value in Format, using the number
                of digits specified in Digits, and a precision of 19.  This function simply calls FloatToStrF
                (1430   ).

    See also:    FloatToStrF (1430   )
                30.12.52           Date

    Synopsis:    Return the current date.

Declaration:     function  Date  :  TDateTime

    Visibility:   default

Description:     Date returns the current date in TDateTime format.

       Errors:   None.

    See also:    Time (1488   ), Now (1457   )


                Listing:  ./sysutex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   T h i s  p r o g r a m 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 ( f o r m a t ( ' Date     i s ( DD  /MM  /YY  ) :  % d /% d /%  d   ' , [dd ,mm  , y y ] ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.53           DateTimeToFileDate

    Synopsis:    Convert a TDateTime value to a file age (integer)

Declaration:     function  DateTimeToFileDate(DateTime:  TDateTime)  :  LongInt

    Visibility:   default

Description:     DateTimeToFileDate  function  converts  a  date/time  indication  in  TDateTime  format  to  a
                filedate function, such as returned for instance by the FileAge (1417   ) function.

       Errors:   None.

    See also:    Time  (1488   ),  Date  (1401   ),  FileDateToDateTime  (1419   ),  DateTimeToSystemTime  (1403   ),
                DateTimeToTimeStamp (1404   )


                Listing:  ./sysutex/ex2.pp


                                                                                1401

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;


                {   T h i s  p r o g r a m 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 t ef u 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 eo f  now    w o u l d  be  :  ' ,DateTimeToFileDate               ( Now   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.54           DateTimeToStr

    Synopsis:    Converts a TDateTime value to a string using a predefined format.

Declaration:     function  DateTimeToStr(DateTime:  TDateTime)  :  String

    Visibility:   default

Description:     DateTimeToStr returns a string representation of  DateTime using the formatting specified
                in LongDateTimeFormat.  It corresponds to a call to FormatDateTime('c',DateTime) (see
                formatchars (1359   )).

       Errors:   None.

    See also:    FormatDateTime (1441   )


                Listing:  ./sysutex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   T h i s  p r o g r a m 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.55           DateTimeToString

    Synopsis:    Converts a TDateTime value to a string with a given format.

Declaration:     procedure  DateTimeToString(out  Result:  String;const  FormatStr:  String;
                                                           const  DateTime:  TDateTime)

    Visibility:   default

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 formatchars (1359   ).

       Errors:   In case a wrong formatting character is found, an EConvertError is raised.

    See also:    FormatDateTime (1441   ), formatchars (1359   )
                                                                                1402

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Listing:  ./sysutex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   T h i s  p r o g r a m 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 n gf u n c t i o n}


                Uses      s y s u t i l;s



                 P r o c e d u r et 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   ;


                 P r o c e d u r eNow    (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  , 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     y y' ) ;
                    Today     (  '" Today     i s  " d /mmm   / y y' ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.56           DateTimeToSystemTime

    Synopsis:    Converts a TDateTime value to a systemtime structure.

Declaration:     procedure  DateTimeToSystemTime(DateTime:  TDateTime;
                                                                  out  SystemTime:  TSystemTime)

    Visibility:   default

Description:     DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime format to
                a system time SystemTime.

       Errors:   None.

    See also:    DateTimeToFileDate (1401   ), SystemTimeToDateTime (1486   ), DateTimeToTimeStamp (1404   )


                Listing:  ./sysutex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DateTimeToSystemTime                 f u n c t i o n}

                                                                                1403

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Uses      s y s u t i l;s


                Var    ST    :  TSystemTime         ;


                Begin
                    DateTimeToSystemTime               (Now   ,ST  ) ;
                    With     S t  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___.____________________________________________________________________________________________________________*
 *___________

                30.12.57           DateTimeToTimeStamp

    Synopsis:    Converts a TDateTime value to a TimeStamp structure.

Declaration:     function  DateTimeToTimeStamp(DateTime:  TDateTime)  :  TTimeStamp

    Visibility:   default

Description:     DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime format to
                a TTimeStamp format.

       Errors:   None.

    See also:    DateTimeToFileDate (1401   ), SystemTimeToDateTime (1486   ), DateTimeToSystemTime (1403   )


                Listing:  ./sysutex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   T h i s  p r o g r a m 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 dp 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.58           DateToStr

    Synopsis:    Converts a TDateTime value to a date string with a predefined format.

Declaration:     function  DateToStr(Date:  TDateTime)  :  String

    Visibility:   default

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).



                                                                                1404

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
       Errors:   None.

    See also:    TimeToStr (1489   ), DateTimeToStr (1402   ), FormatDateTime (1441   ), StrToDate (1478   )


                Listing:  ./sysutex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D a t e T o 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(Format      ( ' Today     i s :  % s ' , [DateToStr      ( Date    ) ] ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.59           DayOfWeek

    Synopsis:    Returns the day of the week.

Declaration:     function  DayOfWeek(DateTime:  TDateTime)  :  Integer

    Visibility:   default

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 (1401   ), DateToStr (1404   )


                Listing:  ./sysutex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DayOfWeek         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     '' s  day    i s   ', LongDayNames         [DayOfWeek       ( Date   ) ] ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.60           DecodeDate

    Synopsis:    Decode a TDateTime to a year,month,day triplet

Declaration:     procedure  DecodeDate(Date:  TDateTime;out  Year:  Word;out  Month:  Word;
                                                 out  Day:  Word)

    Visibility:   default

Description:     DecodeDate  decodes  the  Year,  Month  and  Day  stored  in  Date,  and  returns  them  in  the
                Year, Month and Day variables.

       Errors:   None.



                                                                                1405

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    See also:    EncodeDate (1410   ), DecodeTime (1406   )


                Listing:  ./sysutex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   T h i s  p r o g r a m 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  , y y ] ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.61           DecodeDateFully

    Synopsis:    Decode a date with additional date of the week.

Declaration:     function  DecodeDateFully(const  DateTime:  TDateTime;out  Year:  Word;
                                                        out  Month:  Word;out  Day:  Word;out  DOW:  Word)
                                                         :  Boolean

    Visibility:   default

Description:     DecodeDateFully, like DecodeDate (1405   ), decodes DateTime in its parts and returns these
                in Year, Month, Day but in addition returns the day of the week in DOW.

       Errors:   None.

    See also:    EncodeDate (1410   ), TryEncodeDate (1492   ), DecodeDate (1405   )
                30.12.62           DecodeTime

    Synopsis:    Decode a TDateTime to a hour,minute,second,millisec quartet

Declaration:     procedure  DecodeTime(Time:  TDateTime;out  Hour:  Word;out  Minute:  Word;
                                                 out  Second:  Word;out  MilliSecond:  Word)

    Visibility:   default

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 (1410   ), DecodeDate (1405   )


                Listing:  ./sysutex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                {   T h i s  p r o g r a m 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
                                                                                1406

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Var    HH  ,MM  , SS  ,MS  :  Word   ;


                Begin
                    DecodeTime       ( Time   ,HH   ,MM  ,SS  ,MS  ) ;
                    W r i t e l n ( f o r m a t('The     t i m e  i s % d :% d :%  d.%  d ' , [hh  ,mm  ,s s ,ms  ] ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.63           DeleteFile

    Synopsis:    Delete a file from the filesystem.

Declaration:     function  DeleteFile(const  FileName:  String)  :  Boolean

    Visibility:   default

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 (1418   ), FileExists (1420   )


                Listing:  ./sysutex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 1;


                {   T h i s  p r o g r a m 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  t o  1 0  do
                        F i l e W r i t e(F  ,L i n e[ 1 ] ,Length     (L i n e ) ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.64           DirectoryExists

    Synopsis:    Check whether a directory exists in the file system.

Declaration:     function  DirectoryExists(const  Directory:  String)  :  Boolean

    Visibility:   default

Description:     DirectoryExists checks whether Directory exists in the filesystem and is actually a di-
                rectory.  If this is the case, the function returns True, otherwise False is returned.

    See also:    FileExists (1420   )


                                                                                1407

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.65           DiskFree

    Synopsis:    Return the amount of free diskspace

Declaration:     function  DiskFree(drive:  Byte)  :  Int64

    Visibility:   default

Description:     DiskFree returns the free space (in bytes) on disk Drive.  Drive is the number of the disk
                drive:


                0 for the current drive.

                1 for the first floppy drive.

                2 for the second floppy drive.

                3 for the first hard-disk partition.

                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
                (1408   ) functions must be mimicked using filenames that reside on the partitions.  For more
                information, see AddDisk (1378   ).

       Errors:   On error, -1 is returned.

    See also:    DiskSize (1408   ), AddDisk (1378   )


                Listing:  ./sysutex/ex27.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D i s k F r e e f 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 k S i z e( 0 ) ) ;
                    W r i t e l n ( '  ( =   ' ,D i s k S i z e( 0 ) 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 td i s k  :   ' ,D i s k f r e e( 0 ) ) ;
                    W r i t e l n ( '  ( =   ' ,D i s k f r e e( 0 ) d i v 1 0 2 4 , 'k ) ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.66           DiskSize

    Synopsis:    Return the total amount of diskspace.

Declaration:     function  DiskSize(drive:  Byte)  :  Int64

    Visibility:   default

Description:     DiskSize returns the size (in bytes) of disk Drive.  Drive is the number of the disk drive:


                0 for the current drive.

                1 for the first floppy drive.

                2 for the second floppy drive.

                3 for the first hard-disk parttion.
                                                                                1408

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                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  (1408   )  and
                DiskSize  functions  must  be  mimicked  using  filenames  that  reside  on  the  partitions.   For
                more information, see AddDisk (1378   )

                For an example, see DiskFree (1408   ).

       Errors:   On error, -1 is returned.

    See also:    DiskFree (1408   ), AddDisk (1378   )
                30.12.67           DisposeStr

    Synopsis:    Dispose an ansistring from the heap.

Declaration:     procedure  DisposeStr(S:  PString)

    Visibility:   default

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.

                For an example, see DisposeStr (1409   ).

       Errors:   None.

    See also:    NewStr (1456   ), AppendStr (1392   ), AssignStr (1393   )
                30.12.68           DoDirSeparators

    Synopsis:    Convert known directory separators to the current directory separator.

Declaration:     procedure  DoDirSeparators(var  FileName:  String)

    Visibility:   default

Description:     This  function  replaces  all  known  directory  separators  in  FileName  to  the  directory  sep-
                arator  character  for  the  current  system.   The  list  of  known  separators  is  specified  in  the
                DirSeparators (1356   ) constant.

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   )


                Listing:  ./sysutex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 2;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT e s t i t ( F   :  S t r i n g) ;

                                                                                1409

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                 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\ w i n 3 2' ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.69           EncodeDate

    Synopsis:    Encode a Year,Month,Day to a TDateTime value.

Declaration:     function  EncodeDate(Year:  Word;Month:  Word;Day:  Word)  :  TDateTime

    Visibility:   default

Description:     EncodeDate encodes the Year, Month and Day variables to a date in TDateTime format.  It
                does the opposite of the DecodeDate (1405   ) 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, an EConvertError (1500   ) exception
                is raised.

    See also:    EncodeTime (1410   ), DecodeDate (1405   )


                Listing:  ./sysutex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e E n c o d e D a t e 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.70           EncodeTime

    Synopsis:    Encode a Hour,Min,Sec,millisec to a TDateTime value.

Declaration:     function  EncodeTime(Hour:  Word;Minute:  Word;Second:  Word;
                                                MilliSecond:  Word)  :  TDateTime



                                                                                1410

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    Visibility:  default

Description:     EncodeTime  encodes  the  Hour,  Minute,  Second,  MilliSecond  variables  to  a  TDateTime
                format result.  It does the opposite of the DecodeTime (1406   ) 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 out of it's valid range, an EConvertError (1500   ) exception
                is raised.

    See also:    EncodeDate (1410   ), DecodeTime (1406   )


                Listing:__./sysutex/ex12.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 2;


                {   T h i s  p r o g r a m 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 tTime     i s   :  ' ,FormatDateTime           ( 'hh  :mm  : s s' ,EnCodeTime    *
 *      (HH  ,MM  , SS  ,MS  ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.71           ExceptAddr

    Synopsis:    Current exception address.

Declaration:     function  ExceptAddr  :  Pointer

    Visibility:   default

Description:     ExceptAddr returns the address from the currently treated exception object when an ex-
                ception is raised, and the stack is unwound.

    See also:    ExceptObject (1412   ), ExceptionErrorMessage (1412   ), ShowException (1462   )
                30.12.72           ExceptFrameCount

    Synopsis:    Number of frames included in an exception backtrace

Declaration:     function  ExceptFrameCount  :  LongInt

    Visibility:   default

Description:     ExceptFrameCount returns the number of frames that are included in an exception stack
                frame  backtrace.  The  function  returns  0  if  there  is  currently  no  exception  being  handled.
                (i.e.  it only makes sense to call this function in an finally..end or except..end block.

       Errors:   None.

    See also:    ExceptFrames (1412   ), ExceptAddr (1411   ), ExceptObject (1412   ), ExceptProc (1356   )



                                                                                1411

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.73           ExceptFrames

    Synopsis:

Declaration:     function  ExceptFrames  :  PPointer

    Visibility:   default

Description:

       Errors:

    See also:    ExceptFrameCount (1411   ), ExceptAddr (1411   ), ExceptObject (1412   ), ExceptProc (1356   )
                30.12.74           ExceptionErrorMessage

    Synopsis:    Return a message describing the exception.

Declaration:     function  ExceptionErrorMessage(ExceptObject:  TObject;
                                                                  ExceptAddr:  Pointer;Buffer:  PChar;
                                                                  Size:  Integer)  :  Integer

    Visibility:   default

Description:     ExceptionErrorMessage creates a string that describes the exception object ExceptObject
                at  address  ExceptAddr.  It  can  be  used  to  display  exception  messages.  The  string  will  be
                stored in the memory pointed to by Buffer, and will at most have Size characters.

                The routine checks whether ExceptObject is a Exception (1505   ) object or not, and adapts
                the output accordingly.

    See also:    ExceptObject (1412   ), ExceptAddr (1411   ), ShowException (1462   )
                30.12.75           ExceptObject

    Synopsis:    Current Exception object.

Declaration:     function  ExceptObject  :  TObject

    Visibility:   default

Description:     ExceptObject returns the currently treated exception object when an exception is raised,
                and the stack is unwound.

       Errors:   If there is no exception, the function returns Nil

    See also:    ExceptAddr (1411   ), ExceptionErrorMessage (1412   ), ShowException (1462   )
                30.12.76           ExcludeTrailingBackslash

    Synopsis:    Strip trailing directory separator from a pathname, if needed.

Declaration:     function  ExcludeTrailingBackslash(const  Path:  String)  :  String

    Visibility:   default

Description:     ExcludeTrailingBackslash is provided for backwards compatibility with Delphi.  Use Ex-
                cludeTrailingPathDelimiter (1413   ) instead.

    See also:    IncludeTrailingPathDelimiter (1450   ), ExcludeTrailingPathDelimiter (1413   ), PathDelim (1364   ),
                IsPathDelimiter (1453   )



                                                                                1412

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.77           ExcludeTrailingPathDelimiter

    Synopsis:    Strip trailing directory separator from a pathname, if needed.

Declaration:     function  ExcludeTrailingPathDelimiter(const  Path:  String)  :  String

    Visibility:   default

Description:     ExcludeTrailingPathDelimiter removes the trailing path delimiter character (PathDelim
                (1364   )) from Path if it is present, and returns the result.

    See also:    ExcludeTrailingBackslash (1412   ), IncludeTrailingPathDelimiter (1450   ), PathDelim (1364   ),
                IsPathDelimiter (1453   )
                30.12.78           ExecuteProcess

    Synopsis:    Execute another process (program).

Declaration:     function  ExecuteProcess(const  Path:  AnsiString;
                                                      const  ComLine:  AnsiString)  :  Integer
                function  ExecuteProcess(const  Path:  AnsiString;
                                                      const  ComLine:  Array  of  AnsiString)  :  Integer

    Visibility:   default

Description:     ExecuteProcess will execute the program in Path,  passing it the arguments in ComLine.
                ExecuteProcess will then wait for the program to finish,  and will return the exit code of
                the executed program.  In case ComLine is a single string, it will be split out in an array of
                strings, taking into account common whitespace and quote rules.

       Errors:   In case the program could not be executed or an other error occurs, an EOSError (1503   )
                exception will be raised.

    See also:    EOSError (1503   )
                30.12.79           ExpandFileName

    Synopsis:    Expand a relative filename to an absolute filename.

Declaration:     function  ExpandFileName(const  FileName:  String)  :  String

    Visibility:   default

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 (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )


                Listing:  ./sysutex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   T h i s  p r o g r a m 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
                                                                                1413

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                 P r o c e d u r eT 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 t o  :   ', ExpandFileName          ( F ) ) ;
                end   ;


                Begin
                    T e s t i t( 'e x 3 3. pp  ') ;
                    T e s t i t(ParamStr      ( 0 ) ) ;
                    T e s t i t( '/ pp / b i n/ w i n 3 2/p p c 3 8 6' ) ;
                    T e s t i t( '\ pp \ b i n\ w i n 3 2\p p c 3 8 6' ) ;
                    T e s t i t( '. ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.80           ExpandUNCFileName

    Synopsis:    Expand a relative filename to an absolute UNC filename.

Declaration:     function  ExpandUNCFileName(const  FileName:  String)  :  String

    Visibility:   default

Description:     ExpandUNCFileName runs ExpandFileName (1413   ) on FileName and then attempts to re-
                place the driveletter by the name of a shared disk.

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )
                30.12.81           ExtractFileDir

    Synopsis:    Extract the drive and directory part of a filename.

Declaration:     function  ExtractFileDir(const  FileName:  String)  :  String

    Visibility:   default

Description:     ExtractFileDir returns only the directory part of  FileName, including a driveletter.  The
                directory name has NO ending directory separator, in difference with ExtractFilePath (1416   ).

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )


                Listing:  ./sysutex/ex34.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 4;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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 ) ;



                                                                                1414

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                  W r i t e l n ( ' Has   Name              :   ' ,E x t r a c t F i l e N a m(eF) ) ;
                  W r i t e l n ( ' Has    Path             :   ' ,E x t r a c t F i l e P a t(hF) ) ;
                  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 x(tF) ) ;
                  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 i(rF) ) ;
                  W r i t e l n ( ' Has    D r i v e        :   ' ,E x t r a c t F i l e D r i v(eF) ) ;
                end   ;


                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\ w i n 3 2\ p p c 3 8 6.e x e' ) ;
                    T e s t i t ( ' /pp  / b i n/ w i n 3 2/p p c 3 8 6.e x e ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.82           ExtractFileDrive

    Synopsis:    Extract the drive part from a filename.

Declaration:     function  ExtractFileDrive(const  FileName:  String)  :  String

    Visibility:   default

Description:     Extracts the drive letter from a filename.  Note that some operating systems do not support
                drive letters.

                For an example, see ExtractFileDir (1414   ).

       Errors:

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )
                30.12.83           ExtractFileExt

    Synopsis:    Return the extension from a filename.

Declaration:     function  ExtractFileExt(const  FileName:  String)  :  String

    Visibility:   default

Description:     ExtractFileExt returns the extension (including the .(dot) character) of  FileName.

                For an example, see ExtractFileDir (1414   ).

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )
                30.12.84           ExtractFileName

    Synopsis:    Extract the filename part from a full path filename.

Declaration:     function  ExtractFileName(const  FileName:  String)  :  String

    Visibility:   default



                                                                                1415

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
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
                (1416   ) and ExtractFileName.

                For an example, see ExtractFileDir (1414   ).

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )
                30.12.85           ExtractFilePath

    Synopsis:    Extract the path from a filename.

Declaration:     function  ExtractFilePath(const  FileName:  String)  :  String

    Visibility:   default

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 (1415   ).

                For an example, see ExtractFileDir (1414   ).

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   ), ExtractRelativePath (1416   )
                30.12.86           ExtractRelativepath

    Synopsis:    Extract a relative path from a filename, given a base directory.

Declaration:     function  ExtractRelativepath(const  BaseName:  String;
                                                              const  DestNAme:  String)  :  String

    Visibility:   default

Description:     ExtractRelativePath  constructs  a  relative  path  to  go  from  BaseName  to  DestName.   If
                DestName  is  on  another  drive  (Not  on  Unix-like  platforms)  then  the  whole  Destname  is
                returned.  Note:  This function does not exist in the Delphi unit.

       Errors:   None.

    See also:    ExtractFileName (1415   ), ExtractFilePath (1416   ), ExtractFileDir (1414   ), ExtractFileDrive
                (1415   ), ExtractFileExt (1415   )


                Listing:  ./sysutex/ex35.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   T h i s  p r o g r a m 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



                                                                                1416

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________


                 P r o c e d u r eT e s t i t ( FromDir     , ToDir     :   S t r i n g) ;


                 b e g i n
                    Write     (  'From    "  ' ,FromDir     , ' "  t o  " ' ,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/ w i n 3 2/p p c 3 8 6' ) ;
                  T e s t i t (  '/ pp / b i n/ w i n 3 2/p p c 3 8 6' , '/ pp / s r c/ c o m p i l e r') ;
                  T e s t i t (  'e : /pp  / b i n/w i n 3 2/ p p c 3 8 6', 'd : / pp / s r c/ c o m p i l e r') ;
                  T e s t i t (  'e : \pp  \ b i n\w i n 3 2\ p p c 3 8 6', 'd : \ pp \ s r c\ c o m p i l e r') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.87           ExtractShortPathName

    Synopsis:    Returns a 8.3 path name

Declaration:     function  ExtractShortPathName(const  FileName:  String)  :  String

    Visibility:   default

Description:     ExtractShortPathName  returns  a  8.3  compliant  filename  that  represents  the  same  file  as
                FileName.  On platforms other than windows, this is FileName itself.

    See also:    ExtractFilePath (1416   ), ExtractFileName (1415   )
                30.12.88           FileAge

    Synopsis:    Return the timestamp of a file.

Declaration:     function  FileAge(const  FileName:  String)  :  LongInt

    Visibility:   default

Description:     FileAge returns the last modification time of file FileName.  The FileDate format can be
                transformed to TDateTime format with the FileDateToDateTime (1419   ) function.

       Errors:   In case of errors, -1 is returned.

    See also:    FileDateToDateTime (1419   ), FileExists (1420   ), FileGetAttr (1420   )


                Listing:  ./sysutex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   T h i s  p r o g r a m 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(' e x 3 6.pp  ' ) ;
                    I f  Fa <>-1     then
                        b e g i n
                       S :=  FileDateTodateTime             ( f a ) ;



                                                                                1417

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                        W r i t e l n(  'I ' 'm   f r o m  ', DateTimeToStr          (S ) )
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.89           FileClose

    Synopsis:    Close a file handle.

Declaration:     procedure  FileClose(Handle:  THandle)

    Visibility:   default

Description:     FileClose closes the file handle Handle.  After this call, attempting to read or write from
                the handle will result in an error.

                For an example, see FileCreate (1418   )

       Errors:   None.

    See also:    FileCreate (1418   ), FileWrite (1425   ), FileOpen (1422   ), FileRead (1423   ), FileTruncate (1425   ),
                FileSeek (1424   )
                30.12.90           FileCreate

    Synopsis:    Create a new file and return a handle to it.

Declaration:     function  FileCreate(const  FileName:  String)  :  THandle
                function  FileCreate(const  FileName:  String;Mode:  Integer)  :  THandle

    Visibility:   default

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  (1423   )  and  FileWrite
                (1425   ) 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 (1418   ), FileWrite (1425   ), FileOpen (1422   ), FileRead (1423   ), FileTruncate (1425   ),
                FileSeek (1424   )


                Listing:  ./sysutex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e F i l e C r e a t e f u n c t i o n}


                Uses      s y s u t i l;s


                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
                       H a l t ( 1 ) ;
                    For    I : = 0  t o  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 := F i l e O p e n ( ' t e s t.d a t ', fmOpenRead        ) ;



                                                                                1418

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                    For    I : = 0  t o  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(kF ,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 := F i l e O p e n(' 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 yt r u n c a t e d f i l e t o   ', I , '  b y t e s.' ) ;
                    F i l e C l o s e(F) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.91           FileDateToDateTime

    Synopsis:    Convert a FileDate value to a TDateTime value.

Declaration:     function  FileDateToDateTime(Filedate:  LongInt)  :  TDateTime

    Visibility:   default

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 (1417   ) or FindFirst
                (1426   )/FindNext (1427   ) functions to TDateTime form.

       Errors:   None.

    See also:    DateTimeToFileDate (1401   )


                Listing:  ./sysutex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 3;


                {   T h i s  p r o g r a m 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 m ef u n c t i o n}


                Uses      s y s u t i l;s


                Var
                    T h i s A g e :   L o n g i n t;


                Begin
                  Write      ( 'e x 1 3. pp   c r e a t e d on   : ' ) ;
                  T h i s A g e:= F i l e A g e(' e x 1 3.pp  ' ) ;
                  W r i t e l n ( DateTimeToStr          (FileDateToDateTime              (T h i s A g e) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                1419

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.92           FileExists

    Synopsis:    Check whether a file exists in the filesystem.

Declaration:     function  FileExists(const  FileName:  String)  :  Boolean

    Visibility:   default

Description:     FileExists returns True if a file with name FileName exists on the disk, False otherwise.

       Errors:   None.

    See also:    FileAge (1417   ), FileGetAttr (1420   ), FileSetAttr (1424   )


                Listing:  ./sysutex/ex38.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   T h i s  p r o g r a m 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 s(ParamStr      ( 0 ) ) Then
                        W r i t e l n(  'A l l  i s  w e l l,   I  seem     t o  e x i s t. ') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.93           FileGetAttr

    Synopsis:    Return attributes of a file.

Declaration:     function  FileGetAttr(const  FileName:  String)  :  LongInt

    Visibility:   default

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 unix, this means that the filename starts with a dot)

                faSysFile     The file is a system file (On unix, this means that the file is a character, block or
                       FIFO file).

                faVolumeId        Volume Label.  Not possible under unix.

                faDirectory       File is a directory.

                faArchive      file is an archive.  Not possible on Unix


       Errors:   In case of error, -1 is returned.

    See also:    FileSetAttr (1424   ), FileAge (1417   ), FileGetDate (1421   )


                Listing:  ./sysutex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 0;


                {   T h i s  p r o g r a m 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



                                                                                1420

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________


                 P r o c e d u r eT 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 ef 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 so f  ' ,Name    ) ;
                end   ;


                 b e g i n
                    t e s t i t ( ' e x 4 0.pp  ' ) ;
                    t e s t i t ( ParamStr      ( 0 ) ) ;
                    t e s t i t ( ' . ') ;
                    t e s t i t ( ' / ') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.94           FileGetDate

    Synopsis:    Return the file time of an opened file.

Declaration:     function  FileGetDate(Handle:  THandle)  :  LongInt

    Visibility:   default

Description:     FileGetdate  returns  the  filetime  of  the  opened  file  with  filehandle  Handle.   It  is  the
                same as FileAge (1417   ),  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 (1417   )


                Listing:  ./sysutex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   T h i s  p r o g r a m 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
                                                                                1421

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                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(eF ) ;
                    W r i t e l n ( ' F i l e c r e 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.95           FileIsReadOnly

    Synopsis:    Check whether a file is read-only.

Declaration:     function  FileIsReadOnly(const  FileName:  String)  :  Boolean

    Visibility:   default

Description:     FileIsReadOnly checks whether FileName exists in the filesystem and is a read-only file.
                If this is the case, the function returns True, otherwise False is returned.

    See also:    FileExists (1420   )
                30.12.96           FileOpen

    Synopsis:    Open an existing file and return a filehandle

Declaration:     function  FileOpen(const  FileName:  String;Mode:  Integer)  :  THandle

    Visibility:   default

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 (1423   ) and FileWrite functions.

 Remark:         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 (1418   ) function.

                For an example, see FileOpen (1422   )

       Errors:   On Error, -1 is returned.

    See also:    FileClose (1418   ), FileWrite (1425   ), FileCreate (1418   ), FileRead (1423   ), FileTruncate (1425   ),
                FileSeek (1424   )



                                                                                1422

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.97           FileRead

    Synopsis:    Read data from a filehandle in a buffer.

Declaration:     function  FileRead(Handle:  THandle;var  Buffer;Count:  LongInt)  :  LongInt

    Visibility:   default

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 (1422   ) call.

                The function returns the number of bytes actually read, or -1 on error.

                For an example, see FileCreate (1418   )

       Errors:   On error, -1 is returned.

    See also:    FileClose (1418   ), FileWrite (1425   ), FileCreate (1418   ), FileOpen (1422   ), FileTruncate (1425   ),
                FileSeek (1424   )
                30.12.98           FileSearch

    Synopsis:    Search for a file in a path.

Declaration:     function  FileSearch(const  Name:  String;const  DirList:  String)  :  String

    Visibility:   default

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 (1413   ), FindFirst (1426   )


                Listing:  ./sysutex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 1;


                {   Program       t o  d e m o n s t r a t et h e  F i l e S e a r c hf u n c t i o n.  }


                Uses      S y s u t i l;s


                Const
                {  $ i f d e f u n i 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 : \d o s; 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 h(FN  ,P  ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1423

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.99           FileSeek

    Synopsis:    Set the current file position on a file handle.

Declaration:     function  FileSeek(Handle:  THandle;FOffset:  LongInt;Origin:  LongInt)
                                              :  LongInt
                function  FileSeek(Handle:  THandle;FOffset:  Int64;Origin:  LongInt)
                                              :  Int64

    Visibility:   default

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.

                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  (1418   ),  FileWrite  (1425   ),  FileCreate  (1418   ),  FileOpen  (1422   ),  FileRead  (1423   ),
                FileTruncate (1425   )


                Listing:__./sysutex/ex42.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 4 2;


                {   T h i s  p r o g r a m 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( ' e x 4 0.pp  ' ,f a R e a d O n l y o r  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 ymade     f i l e h i d d e n and    r e a d- o n l y. ')
                    e l s e
                        W r i t e l n(  'C o u l n d'' t  make     f i l e  h i d d e n and    r e a d- o n l y. ') ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.100            FileSetAttr

    Synopsis:    Set the attributes of a file.

Declaration:     function  FileSetAttr(const  Filename:  String;Attr:  LongInt)  :  LongInt

    Visibility:   default

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.

                This function is not implemented on Unixes.

       Errors:   On error, -1 is returned (always on Unixes).

    See also:    FileGetAttr (1420   ), FileGetDate (1421   ), FileSetDate (1425   )



                                                                                1424

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.101            FileSetDate

    Synopsis:    Set the date of a file.

Declaration:     function  FileSetDate(Handle:  THandle;Age:  LongInt)  :  LongInt
                function  FileSetDate(const  FileName:  String;Age:  LongInt)  :  LongInt

    Visibility:   default

Description:     FileSetDate sets the file date of the open file with handle Handle or to Age, where Age is
                a DOS date-and-time stamp value.

                Alternatively, the filename may be specified with the FileName argument.  This variant of
                the  call  is  mandatory  on  unices,  since  there  is  no  OS  support  for  setting  a  file  timestamp
                based on a handle.  (the handle may not be a real file at all).

                The function returns zero if successfull.

       Errors:   On Unix, the handle variant always returns -1, since this is impossible to implement.  On
                Windows and DOS, a negative error code is returned.
                30.12.102            FileTruncate

    Synopsis:    Truncate an open file to a given size.

Declaration:     function  FileTruncate(Handle:  THandle;Size:  Int64)  :  Boolean

    Visibility:   default

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.

                For an example, see FileCreate (1418   ).

       Errors:   On error, the function returns False.

    See also:    FileClose  (1418   ),  FileWrite  (1425   ),  FileCreate  (1418   ),  FileOpen  (1422   ),  FileRead  (1423   ),
                FileSeek (1424   )
                30.12.103            FileWrite

    Synopsis:    Write data from a buffer to a given filehandle.

Declaration:     function  FileWrite(Handle:  THandle;const  Buffer;Count:  LongInt)
                                                :  LongInt

    Visibility:   default

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.

                For an example, see FileCreate (1418   ).

       Errors:   In case of error, -1 is returned.

    See also:    FileClose (1418   ), FileCreate (1418   ), FileOpen (1422   ), FileRead (1423   ), FileTruncate (1425   ),
                FileSeek (1424   )
                                                                                1425

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.104            FindClose

    Synopsis:    Close a find handle

Declaration:     procedure  FindClose(var  F:  TSearchRec)

    Visibility:   default

Description:     FindClose ends a series of FindFirst (1426   )/FindNext (1427   ) calls, and frees any memory
                used  by  these  calls.  It  is  absolutely  necessary  to  do  this  call,  or  huge  memory  losses  may
                occur.

                For an example, see FindFirst (1426   ).

       Errors:   None.

    See also:    FindFirst (1426   ), FindNext (1427   )
                30.12.105            FindCmdLineSwitch

    Synopsis:    Check whether a certain switch is present on the command-line.

Declaration:     function  FindCmdLineSwitch(const  Switch:  String;
                                                           const  Chars:  TSysCharSet;IgnoreCase:  Boolean)
                                                             :  Boolean
                function  FindCmdLineSwitch(const  Switch:  String;IgnoreCase:  Boolean)
                                                             :  Boolean
                function  FindCmdLineSwitch(const  Switch:  String)  :  Boolean

    Visibility:   default

Description:     FindCmdLineSwitch will check all command-line arguments for the presence of the option
                Switch.  It  will  return  True  if  it  was  found,  False  otherwise.  Characters  that  appear  in
                Chars  (default  is  SwitchChars  (1366   ))  are  assumed  to  indicate  an  option  (switch).  If  the
                parameter IgnoreCase is True, case will be ignored when looking for the switch.  Default is
                to search case sensitive.

       Errors:   None.

    See also:    SwitchChars (1366   )
                30.12.106            FindFirst

    Synopsis:    Start a file search and return a findhandle

Declaration:     function  FindFirst(const  Path:  String;Attr:  LongInt;
                                              out  Rslt:  TSearchRec)  :  LongInt

    Visibility:   default

Description:     FindFirst looks for files that match the name (possibly with wildcards) in Path and extra
                attributes 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 Unix-like platforms)
                otherwise.

                Attr is an or-ed combination of the following constants:


                faReadOnly         The file is read-only.

                faHidden       The file is hidden.  (On unix, this means that the filename starts with a dot)



                                                                                1426

               _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________
               faSysFile     The file is a system file (On unix, this means that the file is a character, block or
                     FIFO file).

               faVolumeId        Drive volume Label.  Not possible under unix.

               faDirectory       File is a directory.

               faArchive      file is an archive.  Not possible on Unix


               It is a common misconception that Attr specifies a set of attributes which must be matched
               in  order  for  a  file  to  be  included  in  the  list.   This  is  not  so:  The  value  of  Attr  specifies
               additional  attributes,  this  means  that  the  returned  files  are  either  normal  files  or  have  an
               attribute which is present in Attr.

               Specifically:  specifying faDirectory as a value for Attr does not mean that only directories
               will be returned.  Normal files and  directories will be returned.

               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 (1426   ) call with the same Rslt
               record.  Failure to do so will result in memory loss.

      Errors:   On error the function returns -1 on Unix-like platforms, a nonzero error code on Windows.

   See also:    FindClose (1426   ), FindNext (1427   )


               Listing:  ./sysutex/ex43.pp
               ____________________________________________________________________________________________________________________*
 *__________
               Program       E x a m p l e 4 3;


               {   T h i s  p r o g r a m 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 :   T S e a r c h R e;c
                      Count      :   L o n g i n t;


               Begin
                   Count    : = 0 ;
                   I f  F i n d F i r s t ( '* ' , f a A n y F i l eand    f a D i r e c t o r,yI n f o)=0    then
                       b e g i n
                      Repeat
                          I n c( Count    ) ;
                          With     I n f o do
                             b e g i n
                              I f  ( A t t r and    f a D i r e c t o r)y =   f a D i r e c t o r ythen
                                 Write    ( 'D i r  :   ' ) ;
                              W r i t e l n( Name   : 4 0 ,S i z e: 1 5 ) ;
                             end   ;
                       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 ds e a r c h.  Found      ' ,Count    , '  m a t c h e s') ;


               End___._____________________________________________________________________________________________________________*
 *__________

               30.12.107            FindNext

   Synopsis:    Find the next entry in a findhandle.



                                                                               1427

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Declaration:     function  FindNext(var  Rslt:  TSearchRec)  :  LongInt

    Visibility:  default

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.

                For an example, see FindFirst (1426   )

       Errors:   On error (no more file is found), a nonzero constant is returned.

    See also:    FindFirst (1426   ), FindClose (1426   )
                30.12.108            FloattoCurr

    Synopsis:    Convert a float to a Currency value.

Declaration:     function  FloattoCurr(const  Value:  Extended)  :  Currency

    Visibility:   default

Description:     FloatToCurr converts the Value floating point value to a Currency value.  It checks whether
                Value is in the valid range of currencies (determined by MinCurrency (1364   ) and MaxCur-
                rency (1364   )).  If not, an EConvertError (1500   ) exception is raised.

       Errors:   If  Value is out of range, an EConvertError (1500   ) exception is raised.

    See also:    EConvertError (1500   ), TryFloatToCurr (1492   ), MinCurrency (1364   ), MaxCurrency (1364   )
                30.12.109            FloatToDateTime

    Synopsis:    Convert a float to a TDateTime value.

Declaration:     function  FloatToDateTime(const  Value:  Extended)  :  TDateTime

    Visibility:   default

Description:     FloatToDateTime converts the Value floating point value to a TDateTime value.  It checks
                whether Value is in the valid range of dates (determined by MinDateTime (1364   ) and Max-
                DateTime (1364   )).  If not, an EConvertError (1500   ) exception is raised.

       Errors:   If  Value is out of range, an EConvertError (1500   ) exception is raised.

    See also:    EConvertError (1500   ), MinDateTime (1364   ), MaxDateTime (1364   )
                30.12.110            FloatToDecimal

    Synopsis:    Convert a float value to a TFloatRec value.

Declaration:     procedure  FloatToDecimal(out  Result:  TFloatRec;const  Value;
                                                        ValueType:  TFloatValue;Precision:  Integer;
                                                        Decimals:  Integer)
                procedure  FloatToDecimal(out  Result:  TFloatRec;Value:  Extended;
                                                        Precision:  Integer;Decimals:  Integer)
                                                                                1428

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    Visibility:  default

Description:     FloatToDecimal  converts  the  float  Value  to  a  float  description  in  the  ResultTFloatRec
                (1370   ) format.  It will store Precision digits in the Digits field, of which at most Decimal
                decimals.

       Errors:   None.

    See also:    TFloatRec (1370   )
                30.12.111            FloatToStr

    Synopsis:    Convert a float value to a string using a fixed format.

Declaration:     function  FloatToStr(Value:  Double)  :  String
                function  FloatToStr(Value:  Double;const  FormatSettings:  TFormatSettings)
                                                 :  String
                function  FloatToStr(Value:  Single)  :  String
                function  FloatToStr(Value:  Single;const  FormatSettings:  TFormatSettings)
                                                 :  String
                function  FloatToStr(Value:  Currency)  :  String
                function  FloatToStr(Value:  Currency;
                                                const  FormatSettings:  TFormatSettings)  :  String
                function  FloatToStr(Value:  Comp)  :  String
                function  FloatToStr(Value:  Comp;const  FormatSettings:  TFormatSettings)
                                                 :  String
                function  FloatToStr(Value:  Int64)  :  String
                function  FloatToStr(Value:  Int64;const  FormatSettings:  TFormatSettings)
                                                 :  String

    Visibility:   default

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  (1430   ).   FloatToStr  is
                completely equivalent to the following call:


                FloatToStrF(Value,  ffGeneral,15,  0);


       Errors:   None.

    See also:    FloatToStrF (1430   ), FormatFloat (1441   ), StrToFloat (1480   )


                Listing:  ./sysutex/ex67.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e F l o a t T o S t r f u n c t i o n}


                Uses      s y s u t i l;s


                 P r o c e d u r eT e s t i t ( V a l u e  :  E x t e n d e d) ;
                                                                                1429

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                 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 r(V 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 - 2 0 ) ;
                    T e s t i t ( 1 . 1e - 2 0 0 ) ;
                    T e s t i t ( 1 . 1e + 3 ) ;
                    T e s t i t ( 1 . 1e + 2 0 ) ;
                    T e s t i t ( 1 . 1e + 2 0 0 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.112            FloatToStrF

    Synopsis:    Convert a float value to a string using a given format.

Declaration:     function  FloatToStrF(Value:  Double;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  String
                function  FloatToStrF(Value:  Double;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  String
                function  FloatToStrF(Value:  Single;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  String
                function  FloatToStrF(Value:  Single;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  String
                function  FloatToStrF(Value:  Comp;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  String
                function  FloatToStrF(Value:  Comp;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  String
                function  FloatToStrF(Value:  Currency;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  String
                function  FloatToStrF(Value:  Currency;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  String
                function  FloatToStrF(Value:  Int64;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  String
                function  FloatToStrF(Value:  Int64;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  String

    Visibility:   default

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:


                                                                                1430

            _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________
            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 (1429   ), FloatToText (1432   )


            Listing:  ./sysutex/ex68.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program       E x a m p l e 6 8;


            {   T h i s  p r o g r a m 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    :  A r r a y  [ T F l o a t F o r m a]t o f  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') ;


             P r o c e d u r eT 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  t o  1 5  do
                   For    J : = 1  t o  4   do
                       For    FF :=  f f g e n e r a lt o   f f c u r r e n c ydo
                          b e g i n
                          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(fV 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  ) ;



                                                                            1431

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                    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 - 1 0 ) ;
                    T e s t i t ( 1 . 1E15   ) ;
                    T e s t i t ( 1 . 1E - 1 5 ) ;
                    T e s t i t ( 1 . 1E100   ) ;
                    T e s t i t ( 1 . 1E - 1 0 0 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.113            FloatToText

    Synopsis:    Return a string representation of a float, with a given format.

Declaration:     function  FloatToText(Buffer:  PChar;Value:  Extended;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  LongInt
                function  FloatToText(Buffer:  PChar;Value:  Extended;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  LongInt

    Visibility:   default

Description:     FloatToText converts the floating point variable Value to a string representation and stores
                it in Buffer.  The conversion is governed by format, Precisison and Digits.  more infor-
                mation on these parameters can be found in FloatToStrF (1430   ).  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 (1429   ), FloatToStrF (1430   )


                Listing:  ./sysutex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 8;


                {   T h i s  p r o g r a m 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    :  A r r a y  [ T F l o a t F o r m a]t o f  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') ;


                 P r o c e d u r eT 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  t o  1 5  do
                       For    J : = 1  t o  4   do
                           For    FF :=  f f g e n e r a lt o   f f c u r r e n c ydo
                              b e g i n
                              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 ) ) ;



                                                                                1432

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                               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 - 1 0 ) ;
                    T e s t i t ( 1 . 1E15   ) ;
                    T e s t i t ( 1 . 1E - 1 5 ) ;
                    T e s t i t ( 1 . 1E100   ) ;
                    T e s t i t ( 1 . 1E - 1 0 0 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.114            FloatToTextFmt

    Synopsis:    Convert a float value to a string using a given mask.

Declaration:     function  FloatToTextFmt(Buffer:  PChar;Value:  Extended;format:  PChar;
                                                      FormatSettings:  TFormatSettings)  :  Integer
                function  FloatToTextFmt(Buffer:  PChar;Value:  Extended;format:  PChar)
                                                        :  Integer

    Visibility:   default

Description:     FloatToTextFmt returns a textual representation of Value in the memory location pointed
                to by Buffer.  it uses the formatting specification in Format to do this.  The return value is
                the number of characters that were written in the buffer.

                For a list of valid formatting characters, see FormatFloat (1441   )

       Errors:   No length checking is performed on the buffer.  The buffer should point to enough memory
                to hold the complete string.  If this is not the case, an access violation may occur.

    See also:    FormatFloat (1441   )
                30.12.115            FmtStr

    Synopsis:    Format a string with given arguments.

Declaration:     procedure  FmtStr(var  Res:  String;const  Fmt:  String;
                                           const  args:  Array  of  const)
                procedure  FmtStr(var  Res:  String;const  Fmt:  String;
                                           const  args:  Array  of  const;
                                           const  FormatSettings:  TFormatSettings)

    Visibility:   default

Description:     FmtStr calls Format (1434   ) with Fmt and Args as arguments, and stores the result in Res.
                For more information on how the resulting string is composed, see Format (1434   ).



                                                                                1433

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
       Errors:   In case of error, a EConvertError exception is raised.

    See also:    Format (1434   ), FormatBuf (1440   )


                Listing:  ./sysutex/ex70.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e F m t S t r  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 , 'F o r  some     n i c e  e x a m p l e so f   f o m a t t i n gs e e %  s .'  , ['Format    *
 * ' ] ) ;
                    W r i t e l n (S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.116            ForceDirectories

    Synopsis:    Create a chain of directories

Declaration:     function  ForceDirectories(const  Dir:  String)  :  Boolean

    Visibility:   default

Description:     ForceDirectories tries to create any missing directories in Dir till the whole path in Dir
                exists.  It returns True if Dir already existed or was created succesfully.  If it failed to create
                any of the parts, False is returned.
                30.12.117            Format

    Synopsis:    Format a string with given arguments.

Declaration:     function  Format(const  Fmt:  String;const  Args:  Array  of  const)  :  String
                function  Format(const  Fmt:  String;const  Args:  Array  of  const;
                                         const  FormatSettings:  TFormatSettings)  :  String

    Visibility:   default

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


                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.  If index
                       is omitted, then the zeroth argument is taken.
                                                                                1434

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
'-'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  (1430   ),  where  the  optional  precision  is  used  to  specify  the  total  number  of
      decimals.  (defalt a valueof 15 is used).  The exponent is formatted using maximally 3
      digits.

      In short, the E specifier formats it's argument 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
      (1430   )).  Precision indicates the number of digits following the decimal point.

      In short, the F specifier formats it's argument 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 argument as follows:

      FloatToStrF(Argument,ffGeneral,Precision,3)

M  Currency  format.   the  next  argument  in  the  var{Args}  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 (1430   )

      In short, the M specifier formats it's argument as follows:

      FloatToStrF(Argument,ffCurrency,9999,Precision)

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.



                                                                1435

            _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________
            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.

            U Unsigned  decimal  format.  The  next  argument  in  the  Args  array  should  be  an  unsigned
                  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.

            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 (1440   )


            Listing:  ./sysutex/ex71.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program       e x a m p l e 7 1;


            { $mode      o b j f p c}


            {   T h i s  p r o g r a m 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;


             P r o c e d u r eT 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 . 4d] ' ;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 : 1 0d] ' ;S := Format       (Fmt   , [ 1 0 ] ) ;w r i t e l(nFmt  : 1 2 ,'  =>    ' ,s ) ;
                   Fmt   :=  '[ % 0 : 1 0 . 4d] '; 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: -10.4     d  ]' ;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 nc a u g h t :   ' ,E .M e s s a g e) ;
                       end  ;
                end  ;
                w r i t e l n ( ' P r e s s e n t e r' ) ;



                                                                            1436

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
    r e a d l n;
end   ;


 P r o c e d u r eT 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 . 4x] '; 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: -10.4      x ]' ;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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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   ;


 P r o c e d u r eT 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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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   ;


 P r o c e d u r eT 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 n(fmt  : 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 n(fmt  : 1 2 ,'=>  *
 *  ' , s) ;
                                                                1437

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
       fmt   :=  '[ % 0 : 1 8 . 1 2s]' ; 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   :=  '[% -*.*   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 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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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   ;


 P r o c e d u r eT 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 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 . 4e] '; 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: -10.4      e ]' ;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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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   ;


 P r o c e d u r eT 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(nFmt  : 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(nFmt  : 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 . 4e] '; S:=  Format      ( Fmt  , [ - 1 . 2 3 4 ] ) ;w r i t e l(nFmt  : 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: -10.4      e ]' ;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(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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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   ;


                                                                1438

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
 P r o c e d u r eT 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(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 . 4e] '; 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 ] )w;r i t e l n(Fmt  : 1 2 ,' =>     ' ,s ) ;
       Fmt   :=  '[%0: -10.4      e ]' ;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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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   ;


 P r o c e d u r eT 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 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 . 4e] '; 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 4 ] )w;r i t e l(nFmt  : 1 2 , ' =>    ' , s ) ;
       Fmt   :=  '[%0: -10.4      e ]' ;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 nc a u g h t :   ' ,E .M e s s a g e) ;
           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
    t e s t s t r i n g;
end___._______________________________________________________________________________________________________________________



                                                                1439

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.118            FormatBuf

    Synopsis:    Format a string with given arguments and store the result in a buffer.

Declaration:     function  FormatBuf(var  Buffer;BufLen:  Cardinal;const  Fmt;
                                              fmtLen:  Cardinal;const  Args:  Array  of  const)
                                                :  Cardinal
                function  FormatBuf(var  Buffer;BufLen:  Cardinal;const  Fmt;
                                              fmtLen:  Cardinal;const  Args:  Array  of  const;
                                              const  FormatSettings:  TFormatSettings)  :  Cardinal

    Visibility:   default

Description:     FormatBuf calls Format (1434   ) and stores the result in Buf.

    See also:    Format (1434   )


                Listing:  ./sysutex/ex72.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 2;


                {   T h i s  p r o g r a m 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=    'F o r  some     n i c e  e x a m p l e s o f  f o m a t t i n gs 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.119            FormatCurr

    Synopsis:    Format a currency

Declaration:     function  FormatCurr(const  Format:  String;Value:  Currency)  :  String
                function  FormatCurr(const  Format:  String;Value:  Currency;
                                                const  FormatSettings:  TFormatSettings)  :  String

    Visibility:   default

Description:     FormatCurr formats the currency  Value according to the formatting rule in Format,  and
                returns the resulting string.

                For an explanation of the formatting characters, see FormatFloat (1441   ).

    See also:    FormatFloat (1441   ), FloatToText (1432   )
                                                                                1440

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.120            FormatDateTime

    Synopsis:    Return a string representation of a TDateTime value with a given format.

Declaration:     function  FormatDateTime(FormatStr:  String;DateTime:  TDateTime)  :  String

    Visibility:   default

Description:     FormatDateTime  formats  the  date  and  time  encoded  in  DateTime  according  to  the  for-
                matting  given  in  FormatStr.   The  complete  list  of  formatting  characters  can  be  found  in
                formatchars (1359   ).

       Errors:   On error (such as an invalid character in the formatting string), and EConvertError excep-
                tion is raised.

    See also:    DateTimeToStr (1402   ), DateToStr (1404   ), TimeToStr (1489   ), StrToDateTime (1479   )


                Listing:  ./sysutex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                {   T h i s  p r o g r a m 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  :nn  ' ,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___.____________________________________________________________________________________________________________*
 *___________

                30.12.121            FormatFloat

    Synopsis:    Format a float according to a certain mask.

Declaration:     function  FormatFloat(const  Format:  String;Value:  Extended)  :  String
                function  FormatFloat(const  Format:  String;Value:  Extended;
                                                 const  FormatSettings:  TFormatSettings)  :  String

    Visibility:   default

Description:     FormatFloat formats the floating-point value given by Value using the format specifications
                in Format.  The format specifier can give format specifications for positive, negative or zero
                values (separated by a semicolon).

                If the formatspecifier is empty or the value needs more than 18 digits to be correctly repre-
                sented, the result is formatted with a call to FloatToStrF (1430   ) with the ffGeneral format
                option.

                The following format specifiers are supported:


                0 is a digit place holder.  If there is a corresponding digit in the value being formatted, then
                       it replaces the 0.  If not, the 0 is left as-is.

                #  is also a digit place holder.  If there is a corresponding digit in the value being formatted,
                       then it replaces the #.  If not, it is removed.  by a space.
                                                                                1441

            _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________
            .determines  the  location  of  the  decimal  point.   Only  the  first  '.'   character  is  taken  into
                  account.  If the value contains digits after the decimal point, then it is replaced by the
                  value of the DecimalSeparator character.

            ,determines the use of the thousand separator character in the output string.  If the format
                  string contains one or more ',' charactes, then thousand separators will be used.  The
                  ThousandSeparator character is used.

            E+   determines the use of scientific notation.  If 'E+' or 'E-' (or their lowercase counterparts)
                  are present then scientific notation is used.  The number of digits in the output string
                  is determined by the number of  0 characters after the 'E+'

            ;This  character  separates  sections  for  positive,  negative,  and  zero  numbers  in  the  format
                  string.


   Errors:   If an error occurs, an exception is raised.

See also:    FloatToStr (1429   )


            Listing:  ./sysutex/ex89.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program       E x a m p l e 8 9;


            {   T h i s  p r o g r a m d e m o n s t r a t e st h e F o r m a t F l o a tf u n c t i o n }


            Uses      s y s u t i l;s


            Const
                NrFormat      =9;
                F o r m a t S t r i n g s:  A r r a y[ 1 . .NrFormat      ]  o f  s t r i n g =  (
                           ' ',
                           '0 ' ,
                           '0 . 0 0 ',
                           '#.##    ',
                           '#,##0.00       ',
                           '# ,##0.00;(# ,##0.00)             ',
                           '# ,##0.00;;       Z e r o' ,
                           '0 . 0 0 0E+00   ' ,
                           '#.###    E-0   ') ;
                N r V a l u e =  5 ;
                F o r m a t V a l u e s:  A r r a y[ 1 . .N r V a l u e]  o f  D o u b l e=
                    ( 1 2 3 4 , - 1 2 3 4 , 0 . 5 , 0 , - 0 . 5 ) ;


                Width       =  1 2 ;
                FWidth      =  2 0 ;


            Var
                I ,J   :   I n t e g e r;
                S   :  S t r i n g;


             b e g i n
                Write    ( 'Format     ' :FWidth     ) ;
                For    I : = 1  t o  N r V a l u e do
                   Write    ( F o r m a t V a l u e[si ] :Width    : 2 ) ;
                W r i t e l n;
                For    I : = 1  t o  NrFormat       do
                    b e g i n
                   Write    ( F o r m a t S t r i n g[si] :FWidth     ) ;
                   For    J : = 1  t o  N r V a l u e do
                       b e g i n



                                                                            1442

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                           S := F o r m a t F l o a(tF o r m a t S t r i n g[sI] , F o r m a t V a l u e[sj] ) ;
                           Write    (S : Width    ) ;
                           end  ;
                        W r i t e l n;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.122            FreeAndNil

    Synopsis:    Free object if needed, and set object reference to Nil

Declaration:     procedure  FreeAndNil(var  obj)

    Visibility:   default

Description:     FreeAndNil will free the object in Obj and will set the reference in Obj to Nil.  The reference
                is set to Nil first, so if an exception occurs in the destructor of the object, the reference will
                be Nil anyway.

       Errors:   Exceptions that occur during the destruction of  Obj are not caught.
                30.12.123            GetAppConfigDir

    Synopsis:    Return the appropriate directory for the application's configuration files.

Declaration:     function  GetAppConfigDir(Global:  Boolean)  :  String

    Visibility:   default

Description:     GetAppConfigDir returns the name of a directory in which the application should store its
                configuration  files  on  the  current  OS.  If  the  parameter  Global  is  True  then  the  directory
                returned is a global directory, i.e.  valid for all users on the system.  If the parameter Global
                is false, then the directory is specific for the user who is executing the program.  On systems
                that do not support multi-user environments, these two directories may be the same.

                The directory which is returned is the name of the directory where the application is supposed
                to store files.  This does not mean that the directory exists, or that the user can write in this
                directory (especially if Global=True).  It just returns the name of the appropriate location.

                On systems where the operating system provides a call to determine this location, this call
                will  be  used.  On  systems  where  there  is  no  such  call,  an  algorithm  is  used  which  reflects
                common practice on that system.

                The application name is deduced from the binary name via the ApplicationName (1392   ) call,
                but can be configured by means of the OnGetApplicationName (1375   ) callback.

       Errors:   None.

    See also:    GetAppConfigFile  (1443   ),  ApplicationName  (1392   ),  OnGetApplicationName  (1375   ),  Cre-
                ateDir (1399   ), SysConfigDir (1367   )
                30.12.124            GetAppConfigFile

    Synopsis:    Return an appropriate name for an application configuration file.

Declaration:     function  GetAppConfigFile(Global:  Boolean)  :  String
                function  GetAppConfigFile(Global:  Boolean;SubDir:  Boolean)  :  String
                                                                                1443

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    Visibility:  default

Description:     GetAppConfigFile returns the name of a file in which the application can store its configu-
                ration parameters.  The Global parameter determines whether it is a global configuration file
                (value True) or a personal configuration file (value False).  The parameter SubDir, in case it
                is set to True, will insert the name of a directory before the filename.  This can be used in case
                the application needs to store other data than configuration data in an application-specific
                directory.  Default behaviour is to set this to False.

                No assumptions should be made about the existence or writeability of this file, or the direc-
                tory where the file should reside.

                On systems where the operating system provides a call to determine the location of config-
                uration files, this call will be used.  On systems where there is no such call, an algorithm is
                used which reflects common practice on that system.

                The application name is deduced from the binary name via the ApplicationName (1392   ) call,
                but can be configured by means of the OnGetApplicationName (1375   ) callback.

       Errors:   None.

    See also:    GetAppConfigDir  (1443   ),  OnGetApplicationName  (1375   ),  ApplicationName  (1392   ),  Cre-
                ateDir (1399   ), ConfigExtension (1361   ), SysConfigDir (1367   )
                30.12.125            GetCurrentDir

    Synopsis:    Return the current working directory of the application.

Declaration:     function  GetCurrentDir  :  String

    Visibility:   default

Description:     GetCurrentDir returns the current working directory.

       Errors:   None.

    See also:    SetCurrentDir (1461   ), DiskFree (1408   ), DiskSize (1408   )


                Listing:  ./sysutex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 8;


                {   T h i s  p r o g r a m 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 yi s  :   ' ,G e t C u r r e n t D i)r;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.126            GetDirs

    Synopsis:    Return a list of directory names from a path.

Declaration:     function  GetDirs(var  DirName:  String;var  Dirs:  Array  of  pchar)  :  LongInt

    Visibility:   default


                                                                                1444

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
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 (1416   )


                Listing:  ./sysutex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   T h i s  p r o g r a m 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 :   A r r a y[ 0 . . 1 2 7 ]o f  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  t o  Count    -1   do
                        b e g i n
                       NewDir     := NewDir    +  '/ '+  S t r P a s(D i r s[ I ] ) ;
                        W r i t e l n( NewDir     ) ;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.127            GetEnvironmentString

    Synopsis:    Return an environment variable by index.

Declaration:     function  GetEnvironmentString(Index:  Integer)  :  String

    Visibility:   default

Description:     GetEnvironmentString returns the Index-th environment variable.  The index is 1 based,
                and is bounded from above by the result of GetEnvironmentVariableCount (1446   ).

                For an example, GetEnvironmentVariableCount (1446   ).

 Remark:         Note that on Windows, environment strings can start with an equal sign (=).  This is a trick
                used to pass the current working directory to a newly created proces.  In this case, extracting
                the variable name as the characters before the first equal sign will result in an empty name.

       Errors:   If there is no environment, an empty string is returned.

    See also:    GetEnvironmentVariable (1446   ), GetEnvironmentVariableCount (1446   )



                                                                                1445

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.128            GetEnvironmentVariable

    Synopsis:    Return the value of an environment variable.

Declaration:     function  GetEnvironmentVariable(const  EnvVar:  String)  :  String

    Visibility:   default

Description:     GetEnvironmentVariable  returns  the  value  of  the  EnvVar  environment  variable.   If  the
                specified variable does not exist or EnvVar is empty, an empty string is returned.

    See also:    GetEnvironmentString (1445   ), GetEnvironmentVariableCount (1446   )
                30.12.129            GetEnvironmentVariableCount

    Synopsis:    Return the number of variables in the environment.

Declaration:     function  GetEnvironmentVariableCount  :  Integer

    Visibility:   default

Description:     GetEnvironmentVariableCount returns the number of variables in the environment.  The
                number is 1 based, but the result may be zero if there are no environment variables.

       Errors:   If there is no environment, -1 may be returned.

    See also:    GetEnvironmentString (1445   ), GetEnvironmentVariable (1446   )


                Listing:  ./sysutex/ex92.pp
                ___________________________________________________________________________________________________________________*
 *___________
                { $h + }
                program       e x a m p l e 9 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e
                    G e t E n v i r o n m e n t V a r i a b l e C o ufnutn c t i o n}


                 u s e s  s y s u t i l;s


                Var
                    I   :  I n t e g e r;


                 b e g i n
                    For    I : = 1  t o  G e t E n v i r o n m e n t V a r i a b l e C o udnot
                        W r i t e l n(i: 3 , '  :   ', G e t E n v i r o n m e n t S t r i(nig) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.130            GetFileHandle

    Synopsis:    Extract OS handle from an untyped file or text file.

Declaration:     function  GetFileHandle(var  f:  File)  :  LongInt
                function  GetFileHandle(var  f:  Text)  :  LongInt

    Visibility:   default

Description:     GetFileHandle returns the operating system handle for the file descriptor F. It can be used
                in various file operations which are not directly supported by the pascal language.

                                                                                1446

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.131            GetLastOSError

    Synopsis:    Return the last code from the OS.

Declaration:     function  GetLastOSError  :  Integer

    Visibility:   default

Description:     GetLastOSError  returns  the  error  code  from  the  last  operating  system  call.  It  does  not
                reset this code.  In general,  it should be called when an operating system call reported an
                error condition.  In that case, GetLastOSError gives extended information about the error.

                No  assumptions  should  be  made  about  the  resetting  of  the  error  code  by  subsequent  OS
                calls.  This may be platform dependent.

    See also:    RaiseLastOSError (1458   )
                30.12.132            GetLocalTime

    Synopsis:    Get the local time.

Declaration:     procedure  GetLocalTime(var  SystemTime:  TSystemTime)

    Visibility:   default

Description:     GetLocalTime returns the system time in a TSystemTime (1356   ) format.

       Errors:   None.

    See also:    Now (1457   ), Date (1401   ), Time (1488   ), TSystemTime (1356   )
                30.12.133            GetModuleName

    Synopsis:    Return the name of the current module

Declaration:     function  GetModuleName(Module:  HMODULE)  :  String

    Visibility:   default

Description:     GetModuleName returns the name of the current module.  On windows, this is the name of
                the executable when executed in an executable, or the name of the library when executed in
                a library.

                On all other platforms, the result is always empty, since they provide no such functionality.
                30.12.134            GetTempDir

    Synopsis:    Return name of system's temporary directory

Declaration:     function  GetTempDir(Global:  Boolean)  :  String
                function  GetTempDir  :  String

    Visibility:   default

Description:     GetTempDir returns the temporary directory of the system.  If  Global is True (the default
                value) it returns the system temporary directory, if it is False then a directory private to
                the user is returned.  The returned name will end with a directory delimiter character.

                These  directories  may  be  the  same.  No  guarantee  is  made  that  this  directory  exists  or  is
                writeable by the user.



                                                                                1447

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                The  OnGetTempDir  (1375   )  handler  may  be  set  to  provide  custom  handling  of  this  rou-
                tine:  One could implement callbacks which take into consideration frameworks like KDE or
                GNOME, and return a different value from the default system implementation.

       Errors:   On error, an empty string is returned.

    See also:    OnGetTempDir (1375   ), GetTempFileName (1448   )
                30.12.135            GetTempFileName

    Synopsis:    Return the name of a temporary file.

Declaration:     function  GetTempFileName(const  Dir:  String;const  Prefix:  String)
                                                         :  String
                function  GetTempFileName  :  String
                function  GetTempFileName(Dir:  PChar;Prefix:  PChar;uUnique:  DWORD;
                                                        TempFileName:  PChar)  :  DWORD

    Visibility:   default

Description:     GetTempFileName returns the name of a temporary file in directory Dir.  The name of the
                file starts with Prefix.

                If  Dir is empty, the value returned by GetTempDir is used, and if  Prefix is empty, 'TMP'
                is used.

                The  OnGetTempFile  (1376   )  handler  may  be  set  to  provide  custom  handling  of  this  rou-
                tine:  One could implement callbacks which take into consideration frameworks like KDE or
                GNOME, and return a different value from the default system implementation.

       Errors:   On error, an empty string is returned.

    See also:    GetTempDir (1447   ), OnGetTempFile (1376   )
                30.12.136            GetUserDir

    Synopsis:    Returns the current user's home directory.

Declaration:     function  GetUserDir  :  String

    Visibility:   default

Description:     GetUserDir  returns  the  home  directory  of  the  current  user.   On  Unix-like  systems  (that
                includes  Mac  OS  X),  this  is  the  value  of  the  HOME  environment  variable.  On  Windows,
                this  is  the  PROFILE  special  folder.   On  all  other  platforms,  the  application  installation
                directory is returned.

                If non-empty, it contains a trailing path delimiter.

    See also:    GetAppConfigDir (1443   )
                30.12.137            GUIDToString

    Synopsis:    Convert a TGUID to a string representation.

Declaration:     function  GUIDToString(const  GUID:  TGUID)  :  String

    Visibility:   default
                                                                                1448

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     GUIDToString converts the GUID identifier in GUID to a string representation in the form


                {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}


                Where each X is a hexadecimal digit.

       Errors:   None.

    See also:    Supports (1485   ), #rtl.system.TGUID (1199   ), StringToGUID (1469   ), IsEqualGuid (1452   )
                30.12.138            HookSignal

    Synopsis:    Hook a specified signal

Declaration:     procedure  HookSignal(RtlSigNum:  Integer)

    Visibility:   default

Description:     This function is declared for Kylix compatibility, but is not implemented.
                30.12.139            IncAMonth

    Synopsis:    Increase a date with a certain amount of months

Declaration:     procedure  IncAMonth(var  Year:  Word;var  Month:  Word;var  Day:  Word;
                                                NumberOfMonths:  Integer)

    Visibility:   default

Description:     IncAMonth increases the date as specified by  Year,  Month,  Day with NumberOfMonths.  It
                takes care of the number of days in a month when calculating the result.

                This function does the same as IncMonth (1450   ), but operates on an already decoded date.

    See also:    IncMonth (1450   )
                30.12.140            IncludeTrailingBackslash

    Synopsis:    Add trailing directory separator to a pathname, if needed.

Declaration:     function  IncludeTrailingBackslash(const  Path:  String)  :  String

    Visibility:   default

Description:     IncludeTrailingBackslash is provided for backwards compatibility with Delphi.  Use In-
                cludeTrailingPathDelimiter (1450   ) instead.

    See also:    IncludeTrailingPathDelimiter (1450   ), ExcludeTrailingPathDelimiter (1413   ), PathDelim (1364   ),
                IsPathDelimiter (1453   )

                                                                                1449

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.141            IncludeTrailingPathDelimiter

    Synopsis:    Add trailing directory separator to a pathname, if needed.

Declaration:     function  IncludeTrailingPathDelimiter(const  Path:  String)  :  String

    Visibility:   default

Description:     IncludeTrailingPathDelimiter adds a trailing path delimiter character (PathDelim (1364   ))
                to Path if none is present yet, and returns the result.

                If  Path is empty, a path delimiter is returned, for Delphi compatibility.

    See also:    IncludeTrailingBackslash (1449   ), ExcludeTrailingPathDelimiter (1413   ), PathDelim (1364   ),
                IsPathDelimiter (1453   )
                30.12.142            IncMonth

    Synopsis:    Increases the month in a TDateTime value with a given amount.

Declaration:     function  IncMonth(const  DateTime:  TDateTime;NumberOfMonths:  Integer)
                                              :  TDateTime

    Visibility:   default

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 (1401   ), Time (1488   ), Now (1457   )


                Listing:  ./sysutex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n c M o n t h f u n c t i o n }


                Uses      s y s u t i l;s


                Var    T h i s D a y  :  TDateTime       ;


                Begin
                    T h i s D a y:= Date   ;
                    W r i t e l n ( 'T h i s D a y  :  ' ,DateToStr       ( T h i s D a y) ) ;
                    W r i t e l n ( ' 6  months      ago    : ' ,DateToStr       ( I n c M o n t h(ThisDay     , - 6 ) ) ) ;
                    W r i t e l n ( ' 6  months      f r o m  now    : '  , DateToStr      ( I n c M o n t h(ThisDay     , 6 ) ) ) ;
                    W r i t e l n ( ' 1 2  months      ago    : ' ,DateToStr       (I n c M o n t h(ThisDay     , - 1 2 ) ) ) ;
                    W r i t e l n ( ' 1 2  months      f r o m now     : '  ,DateToStr       ( I n c M o n t h(ThisDay     , 1 2 ) *
 *) ) ;
                    W r i t e l n ( ' 1 8  months      ago    : ' ,DateToStr       (I n c M o n t h(ThisDay     , - 1 8 ) ) ) ;
                    W r i t e l n ( ' 1 8  months      f r o m now     : '  ,DateToStr       ( I n c M o n t h(ThisDay     , 1 8 ) *
 *) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________


                                                                                1450

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.143            InquireSignal

    Synopsis:    Check whether a signal handler is set

Declaration:     function  InquireSignal(RtlSigNum:  Integer)  :  TSignalState

    Visibility:   default

Description:     This function is declared for Kylix compatibility, but is not implemented.
                30.12.144            IntToHex

    Synopsis:    Convert an integer value to a hexadecimal string.

Declaration:     function  IntToHex(Value:  Integer;Digits:  Integer)  :  String
                function  IntToHex(Value:  Int64;Digits:  Integer)  :  String
                function  IntToHex(Value:  QWord;Digits:  Integer)  :  String

    Visibility:   default

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 (1451   )


                Listing:  ./sysutex/ex73.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n t T o H e x 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  t o  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___.____________________________________________________________________________________________________________*
 *___________

                30.12.145            IntToStr

    Synopsis:    Convert an integer value to a decimal string.

Declaration:     function  IntToStr(Value:  Integer)  :  String
                function  IntToStr(Value:  Int64)  :  String
                function  IntToStr(Value:  QWord)  :  String

    Visibility:   default


                                                                                1451

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
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 (1451   ), StrToInt (1482   )


                Listing:  ./sysutex/ex74.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I n t T o S t r 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  t o  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___.____________________________________________________________________________________________________________*
 *___________

                30.12.146            IsDelimiter

    Synopsis:    Check whether a given string is a delimiter character.

Declaration:     function  IsDelimiter(const  Delimiters:  String;const  S:  String;
                                                 Index:  Integer)  :  Boolean

    Visibility:   default

Description:     IsDelimiter checks whether the Index-th character in the string S is a delimiter character
                as passed in Delimiters.  If  Index is out of range, False is returned.

       Errors:   None.

    See also:    LastDelimiter (1454   )
                30.12.147            IsEqualGUID

    Synopsis:    Check whether two TGUID variables are equal.

Declaration:     function  IsEqualGUID(const  guid1:  TGUID;const  guid2:  TGUID)  :  Boolean

    Visibility:   default

Description:     IsEqualGUID  checks  whether  guid1  and  guid2  are  equal,  and  returns  True  if  this  is  the
                case, or False otherwise.

       Errors:

    See also:    Supports (1485   ), #rtl.system.TGUID (1199   ), StringToGUID (1469   ), GuidToString (1448   )


                                                                                1452

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.148            IsLeapYear

    Synopsis:    Determine whether a year is a leap year.

Declaration:     function  IsLeapYear(Year:  Word)  :  Boolean

    Visibility:   default

Description:     IsLeapYear returns True if  Year is a leap year, False otherwise.

       Errors:   None.

    See also:    IncMonth (1450   ), Date (1401   )


                Listing:  ./sysutex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s L e a p Y e a r f u n c t i o n}


                Uses      s y s u t i l;s


                Var    YY  ,MM  , dd   :  Word    ;


                 P r o c e d u r eT 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 a r(Y) ) ;
                end   ;


                Begin
                    DeCodeDate       ( Date   , YY  ,mm  ,dd  ) ;
                    T e s t Y e a r(y y) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.149            IsPathDelimiter

    Synopsis:    Is the character at the given position a pathdelimiter ?

Declaration:     function  IsPathDelimiter(const  Path:  String;Index:  Integer)  :  Boolean

    Visibility:   default

Description:     IsPathDelimiter returns True if the character at position Index equals PathDelim (1364   ),
                i.e.  if it is a path delimiter character for the current platform.

       Errors:   IncludeTrailingPathDelimiter (1450   )ExcludeTrailingPathDelimiter (1413   )PathDelim (1364   )
                30.12.150            IsValidIdent

    Synopsis:    Check whether a string is a valid identifier name.

Declaration:     function  IsValidIdent(const  Ident:  String)  :  Boolean



                                                                                1453

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
    Visibility:  default

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.


                Listing:__./sysutex/ex75.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 7 5;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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
                    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 ( ' 1MyObject       ') ;
                    T e s t i t ( ' My@Object       ') ;
                    T e s t i t ( 'M123    ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.151            LastDelimiter

    Synopsis:    Return the last occurrence of a set of delimiters in a string.

Declaration:     function  LastDelimiter(const  Delimiters:  String;const  S:  String)
                                                      :  Integer

    Visibility:   default

Description:     LastDelimiter returns the last  occurrence of any character in the set Delimiters in the
                string S.

       Errors:


                Listing:__./sysutex/ex88.pp________________________________________________________________________________________*
 *___________

                Program       e x a m p l e 8 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e L a s t D e l i m i t e rf u n c t i o n}


                 u s e s S y s U t i l s;


                 b e g i n
                    W r i t e l n(L a s t D e l i m i t e(r'\ . : ', ' c: \ f i l e n a m e.e x t' ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________
                                                                                1454

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.152            LeftStr

    Synopsis:    Return a number of characters starting at the left of a string.

Declaration:     function  LeftStr(const  S:  String;Count:  Integer)  :  String

    Visibility:   default

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 (1460   ), TrimLeft (1490   ), TrimRight (1491   ), Trim (1490   )


                Listing:  ./sysutex/ex76.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 6;


                {   T h i s  p r o g r a m 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.153            LoadStr

    Synopsis:    Load a string from the resource tables.

Declaration:     function  LoadStr(Ident:  Integer)  :  String

    Visibility:   default

Description:     This function is not yet implemented.  resources are not yet supported.

       Errors:
                30.12.154            LowerCase

    Synopsis:    Return a lowercase version of a string.

Declaration:     function  LowerCase(const  s:  String)  :  String;    Overload
                function  LowerCase(const  V:  variant)  :  String;    Overload

    Visibility:   default

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 (1383   ), UpperCase (1496   ), AnsiUpperCase (1391   )


                Listing:  ./sysutex/ex77.pp



                                                                                1455

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e L o w e r C a s e 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     o u t  a l l  LoWeRcAsE        ! ' ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.155            MSecsToTimeStamp

    Synopsis:    Convert a number of milliseconds to a TDateTime value.

Declaration:     function  MSecsToTimeStamp(MSecs:  Comp)  :  TTimeStamp

    Visibility:   default

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 (1489   ), DateTimeToTimeStamp (1404   )


                Listing:  ./sysutex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   T h i s  p r o g r a m 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 e1 / 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 ss 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 ss i n c e 1 / 1 / 0 0 0 1  :  ' ,MS  ) ;
                    MS :=  MS - 1 0 0 0 * 3 6 0 0 * 2 ;
                    TS :=  MSecsToTimeStamp            (MS  ) ;
                    DT :=  TimeStampToDateTime              ( TS  ) ;
                    W r i t e l n ( 'Now    m i n u s  1  day     :  ' ,DateTimeToStr          (DT  ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.156            NewStr

    Synopsis:    Allocate a new ansistring on the heap.

Declaration:     function  NewStr(const  S:  String)  :  PString

    Visibility:   default



                                                                                1456

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
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.

                For an example, see AssignStr (1393   ).

       Errors:   If not enough memory is present, an EOutOfMemory exception will be raised.

    See also:    AssignStr (1393   ), DisposeStr (1409   )
                30.12.157            Now

    Synopsis:    Returns the current date and time.

Declaration:     function  Now  :  TDateTime

    Visibility:   default

Description:     Now returns the current date and time.  It is equivalent to Date+Time.

       Errors:   None.

    See also:    Date (1401   ), Time (1488   )


                Listing:  ./sysutex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Now    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 ( 'Now     :  ' ,DateTimeToStr          (Now   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.158            OutOfMemoryError

    Synopsis:    Raise an EOutOfMemory exception

Declaration:     procedure  OutOfMemoryError

    Visibility:   default

Description:     OutOfMemoryError  raises  an  EOutOfMemory  (1503   )  exception,  with  an  exception  object
                that has been allocated on the heap at program startup.  The program should neved create
                an EOutOfMemory (1503   ) exception, but always call this routine.

    See also:    EOutOfMemory (1503   )
                                                                                1457

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.159            QuotedStr

    Synopsis:    Return a quotes version of a string.

Declaration:     function  QuotedStr(const  S:  String)  :  String

    Visibility:   default

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 (1384   ), AnsiExtractQuotedStr (1381   )


                Listing:  ./sysutex/ex78.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Q u o t e d S t r 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 :=  '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(rS ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.160            RaiseLastOSError

    Synopsis:    Raise an exception with the last Operating System error code.

Declaration:     procedure  RaiseLastOSError

    Visibility:   default

Description:     RaiseLastOSError raises an EOSError (1503   ) exception with the error code returned by
                GetLastOSError.  If the Error code is nonzero, then the corresponding error message will be
                returned.  If the error code is zero, a standard message will be returned.

       Errors:   This  procedure  may  not  be  implemented  on  all  platforms.   If  it  is  not,  then  a  normal
                Exception (1505   ) will be raised.

    See also:    EOSError (1503   ), GetLastOSError (1447   ), Exception (1505   )
                30.12.161            RemoveDir

    Synopsis:    Remove a directory from the filesystem.

Declaration:     function  RemoveDir(const  Dir:  String)  :  Boolean

    Visibility:   default

                                                                                1458

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     RemoveDir removes directory  Dir from the disk.  If the directory is not absolue,  it is ap-
                pended to the current working directory.

                For an example, see CreateDir (1399   ).

       Errors:   In case of error (e.g.  the directory isn't empty) the function returns False.  If successful,
                True is returned.
                30.12.162            RenameFile

    Synopsis:    Rename a file.

Declaration:     function  RenameFile(const  OldName:  String;const  NewName:  String)
                                                 :  Boolean

    Visibility:   default

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 (1407   )


                Listing:  ./sysutex/ex44.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e n a m e F i l e f 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 yrenamed       f i l e s.' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.163            ReplaceDate

    Synopsis:    Replace the date part of a date/time stamp

Declaration:     procedure  ReplaceDate(var  DateTime:  TDateTime;const  NewDate:  TDateTime)

    Visibility:   default

Description:     ReplaceDate  replaces  the  date  part  of  DateTime  with  NewDate.   The  time  part  is  left
                unchanged.

    See also:    ReplaceTime (1460   )


                                                                                1459

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.164            ReplaceTime

    Synopsis:    Replace the time part

Declaration:     procedure  ReplaceTime(var  dati:  TDateTime;NewTime:  TDateTime)

    Visibility:   default

Description:     ReplaceTime  replaces  the  time  part  in  dati  with  NewTime.   The  date  part  remains  un-
                touched.

       Errors:
                30.12.165            RightStr

    Synopsis:    Return a number of characters from a string, starting at the end.

Declaration:     function  RightStr(const  S:  String;Count:  Integer)  :  String

    Visibility:   default

Description:     RightStr returns the Count rightmost characters of S. It is equivalent to a call to Copy(S,Length(S)+1-Count,Count*
 *).

                If  Count is larger than the actual length of  S only the real length will be used.

       Errors:   None.

    See also:    LeftStr (1455   ), Trim (1490   ), TrimLeft (1490   ), TrimRight (1491   )


                Listing:  ./sysutex/ex79.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R i g h 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 ( 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'y,z2 0 ) ) ;
                    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'y,z1 5 ) ) ;
                    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'y,z1 ) ) ;
                    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'y,z2 0 0 ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.166            SafeLoadLibrary

    Synopsis:    Load a library safely

Declaration:     function  SafeLoadLibrary(const  FileName:  AnsiString;ErrorMode:  DWord)
                                                         :  HMODULE

    Visibility:   default

Description:     SafeLoadLibrary saves and restores some registers before and after issuing a call to LoadLibrary.

       Errors:   None.
                                                                                1460

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.167            SameFileName

    Synopsis:    Are two filenames referring to the same file ?

Declaration:     function  SameFileName(const  S1:  String;const  S2:  String)  :  Boolean

    Visibility:   default

Description:     SameFileName returns True if calling AnsiCompareFileName (1379   ) with arguments S1 and
                S2 returns 0, and returns False otherwise.

       Errors:   None.

    See also:    AnsiCompareFileName (1379   )
                30.12.168            SameText

    Synopsis:    Checks whether 2 strings are the same (case insensitive)

Declaration:     function  SameText(const  s1:  String;const  s2:  String)  :  Boolean

    Visibility:   default

Description:     SameText calls CompareText (1398   ) with S1 and S2 as parameters and returns True if the
                result of that call is zero, or False otherwise.

       Errors:   None.

    See also:    CompareText (1398   ), AnsiSameText (1384   ), AnsiSameStr (1384   )
                30.12.169            SetCurrentDir

    Synopsis:    Set the current directory of the application.

Declaration:     function  SetCurrentDir(const  NewDir:  String)  :  Boolean

    Visibility:   default

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 (1444   )
                30.12.170            SetDirSeparators

    Synopsis:    Set the directory separators to the known directory separators.

Declaration:     function  SetDirSeparators(const  FileName:  String)  :  String

    Visibility:   default

Description:     SetDirSeparators returns FileName with all possible DirSeparators replaced by OSDirSeparator.

       Errors:   None.

    See also:    ExpandFileName (1413   ), ExtractFilePath (1416   ), ExtractFileDir (1414   )


                Listing:  ./sysutex/ex47.pp



                                                                                1461

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   T h i s  p r o g r a m 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 r sf 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 e t D i r S e p a r a t o r(s'/pp \ b i n/ w i n 3 2\p p c 3 8 6' ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.171            ShowException

    Synopsis:    Show the current exception to the user.

Declaration:     procedure  ShowException(ExceptObject:  TObject;ExceptAddr:  Pointer)

    Visibility:   default

Description:     ShowException shows a message stating that a ExceptObject was raised at address ExceptAddr.
                It uses ExceptionErrorMessage (1412   ) to create the message, and is aware of the fact whether
                the application is a console application or a GUI application.  For a console application, the
                message  is  written  to  standard  error  output.   For  a  GUI  application,  OnShowException
                (1376   ) is executed.

       Errors:   If, for a GUI application, OnShowException (1376   ) is not set, no message will be displayed
                to the user.

                The exception message can be at most 255 characters long:  It is possible that no memory
                can  be  allocated  on  the  heap,  so  ansistrings  are  not  available,  so  a  shortstring  is  used  to
                display the message.

    See also:    ExceptObject (1412   ), ExceptAddr (1411   ), ExceptionErrorMessage (1412   )
                30.12.172            Sleep

    Synopsis:    Suspend execution of a program for a certain time.

Declaration:     procedure  Sleep(milliseconds:  Cardinal)

    Visibility:   default

Description:     Sleep  suspends  the  execution  of  the  program  for  the  specified  number  of  milliseconds
                (milliseconds).  After the specified period has expired, program execution resumes.

 Remark:         The indicated time is not exact, i.e.  it is a minimum time.  No guarantees are made as to
                the exact duration of the suspension.
                30.12.173            SScanf

    Synopsis:    Scan a string for substrings and return the substrings

Declaration:     function  SScanf(const  s:  String;const  fmt:  String;
                                         const  Pointers:  Array  of  Pointer)  :  Integer

    Visibility:   default

                                                                                1462

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     SSCanF scans the string S for the elements specified in Fmt, and returns the elements in the
                pointers in Pointers.  The Fmt can contain placeholders of the form %X where X can be one
                of the following characters:


                d Placeholder for a decimal number.

                fPlaceholder for a floating point number (an extended)

                sPlaceholder for a string of arbitrary length.

                cPlaceholder for a single character


                The  Pointers  array  contains  a  list  of  pointers,  each  pointer  should  point  to  a  memory
                location of a type that corresponds to the type of placeholder in that position:


                d A pointer to an integer.

                fA pointer to an extended.

                sA pointer to an ansistring.

                cA pointer to a single character.


       Errors:   No error checking is performed on the type of the memory location.

    See also:    Format (1434   )
                30.12.174            StrAlloc

    Synopsis:    Allocate a null-terminated string on the heap.

Declaration:     function  StrAlloc(Size:  cardinal)  :  PChar

    Visibility:   default

Description:     StrAlloc reserves memory on the heap for a string with length Len, terminating #0 included,
                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 (1123   ) function of the Strings
                unit.

                For an example, see StrBufSize (1463   ).

       Errors:   None.

    See also:    StrBufSize (1463   ), StrDispose (1466   ), #rtl.strings.StrAlloc (1123   )
                30.12.175            StrBufSize

    Synopsis:    Return the size of a null-terminated string allocated on the heap.

Declaration:     function  StrBufSize(Str:  PChar)  :  SizeUInt

    Visibility:   default

Description:     StrBufSize returns the memory allocated for Str.  This function ONLY gives the correct
                result if  Str was allocated using StrAlloc (1463   ).

       Errors:   If no more memory is available, a runtime error occurs.

    See also:    StrAlloc (1463   ), StrDispose (1466   )
                                                                                1463

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Listing:  ./sysutex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r B u f S i z e f 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   :  P c h a r;


                Begin
                     P :=  S t r A l l o c(Length    ( S ) + 1 ) ;
                      StrPCopy      (P , S ) ;
                      Write     ( P ,   '  h a s  l e n g t h ' ,l e n g t h(S  ) ) ;
                      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___.____________________________________________________________________________________________________________*
 *___________

                30.12.176            StrByteType

    Synopsis:    Return the type of byte in a null-terminated string for a multi-byte character set

Declaration:     function  StrByteType(Str:  PChar;Index:  Cardinal)  :  TMbcsByteType

    Visibility:   default

Description:     StrByteType returns the type of byte in the null-terminated string Str at (0-based) position
                Index.

       Errors:   No checking on the index is performed.

    See also:    TMbcsByteType (1372   ), ByteType (1395   )
                30.12.177            strcat

    Synopsis:    Concatenate 2 null-terminated strings.

Declaration:     function  strcat(dest:  pchar;source:  pchar)  :  pchar

    Visibility:   default

Description:     Attaches Source to Dest and returns Dest.

       Errors:   No length checking is performed.

    See also:    StrLCat (1470   )


                Listing:  ./stringex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                Uses     s t r i n g s;


                {   Program       t o  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.  }

                                                                                1464

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Const      P1   :   PChar     =   'T h i s  i s  a   PChar     S t r i n g. ';


                Var    P2    :  PChar    ;


                 b e g i n
                    P2 :=  S t r A l l o c (S t r L e n(P1  ) * 2 + 1 ) ;
                    StrMove       (P2  , P1  ,S t r L e n(P1  ) + 1 ) ; {   P2 = P1   }
                    S t r C a t ( P2  ,P1  ) ;                          {   Append      P2   o n c e  more     }
                    W r i t e l n ( 'P2    :   ',P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.178            StrCharLength

    Synopsis:    Return the length of a null-terminated string in characters.

Declaration:     function  StrCharLength(const  Str:  PChar)  :  Integer

    Visibility:   default

Description:     StrCharLength returns the length of the null-terminated string Str (a widestring) in char-
                acters (not in bytes).  It uses the widestring manager to do this.
                30.12.179            strcomp

    Synopsis:    Compare 2 null-terminated strings, case sensitive.

Declaration:     function  strcomp(str1:  pchar;str2:  pchar)  :  SizeInt

    Visibility:   default

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.


                For an example, see StrLComp (1470   ).

       Errors:   None.

    See also:    StrLComp (1470   ), StrIComp (1468   ), StrLIComp (1473   )
                30.12.180            strcopy

    Synopsis:    Copy a null-terminated string

Declaration:     function  strcopy(dest:  pchar;source:  pchar)  :  pchar

    Visibility:   default

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 (1475   ), StrLCopy (1471   ), StrECopy (1466   )



                                                                                1465

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Listing:  ./stringex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                Uses     s t r i n g s;


                {   Program       t o  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  :  PP =  ' ,PP  ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.181            StrDispose

    Synopsis:    Dispose of a null-terminated string on the heap.

Declaration:     procedure  StrDispose(Str:  PChar)

    Visibility:   default

Description:     StrDispose frees any memory allocated for Str.  This function will only function correctly
                if  Str has been allocated using StrAlloc (1463   ) from the SysUtils unit.

                For an example, see StrBufSize (1463   ).

       Errors:   If an invalid pointer is passed, or a pointer not allocated with StrAlloc, an error may occur.

    See also:    StrBufSize (1463   ), StrAlloc (1463   ), StrDispose (1466   )
                30.12.182            strecopy

    Synopsis:    Copy a null-terminated string, return a pointer to the end.

Declaration:     function  strecopy(dest:  pchar;source:  pchar)  :  pchar

    Visibility:   default

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 (1471   ), StrCopy (1465   )


                Listing:  ./stringex/ex6.pp
                                                                                1466

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                Uses     s t r i n g s;


                {   Program       t o  d e m o n s t r a t et h e  S t r E 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.' ;


                Var    PP    :  PChar    ;


                 b e g i n
                    PP :=  S t r A l l o c (S t r L e n(P ) + 1 ) ;
                    I f  L o n g i n t(StrECopy      ( PP  ,P )) - L o n g i n t(PP )<>   S t r L e n(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  ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.183            strend

    Synopsis:    Return a pointer to the end of a null-terminated string

Declaration:     function  strend(p:  pchar)  :  pchar

    Visibility:   default

Description:     Returns a pointer to the end of  P. (i.e.  to the terminating null-character.

       Errors:   None.

    See also:    StrLen (1471   )


                Listing:  ./stringex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                Uses     s t r i n g s;


                {   Program       t o  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 )<>  S t r L e n(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___.____________________________________________________________________________________________________________*
 *___________

                30.12.184            StrFmt

    Synopsis:    Format a string with given arguments, store the result in a buffer.



                                                                                1467

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Declaration:     function  StrFmt(Buffer:  PChar;Fmt:  PChar;const  args:  Array  of  const)
                                          :  Pchar
                function  StrFmt(Buffer:  PChar;Fmt:  PChar;const  Args:  Array  of  const;
                                        const  FormatSettings:  TFormatSettings)  :  PChar

    Visibility:  default

Description:     StrFmt  will  format  fmt  with  Args,  as  the  Format  (1434   )  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 (1434   ).

    See also:    StrLFmt (1472   ), FmtStr (1433   ), Format (1434   ), FormatBuf (1440   )


                Listing:  ./sysutex/ex80.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r F m t  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 ] ,' F o r  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___.____________________________________________________________________________________________________________*
 *___________

                30.12.185            stricomp

    Synopsis:    Compare 2 null-terminated strings, case insensitive.

Declaration:     function  stricomp(str1:  pchar;str2:  pchar)  :  SizeInt

    Visibility:   default

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 (1470   ), StrComp (1465   ), StrLIComp (1473   )


                Listing:  ./stringex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                Uses     s t r i n g s;


                {   Program       t o  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.' ;



                                                                                1468

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                           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 sa r e  t h e  same   . ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.186            StringReplace

    Synopsis:    Replace occurrences of one substring with another in a string.

Declaration:     function  StringReplace(const  S:  String;const  OldPattern:  String;
                                                     const  NewPattern:  String;Flags:  TReplaceFlags)
                                                      :  String

    Visibility:   default

Description:     StringReplace  searches  the  string  S  for  occurrences  of  the  string  OldPattern  and,  if  it
                is  found,  replaces  it  with  NewPattern.   It  returns  the  resulting  string.   The  behaviour  of
                StringReplace can be runed with Flags, which is of type TReplaceFlags (1372   ).  Standard
                behaviour is to replace only the first occurrence of OldPattern, and to search case sensitively.

       Errors:   None.

    See also:    TReplaceFlags (1372   )
                30.12.187            StringToGUID

    Synopsis:    Convert a string to a native TGUID type.

Declaration:     function  StringToGUID(const  S:  String)  :  TGUID

    Visibility:   default

Description:     StringToGUID converts the string S to a valid GUID. The string S should be of the form


                {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}


                Where each X is a hexadecimal digit.  The dashes and braces are required.

       Errors:   In  case  S  contains  an  invalid  GUID  representation,  a  EConvertError  (1500   )  exception  is
                raised.

    See also:    Supports (1485   ), #rtl.system.TGUID (1199   ), GUIDToString (1448   ), IsEqualGuid (1452   )
                                                                                1469

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.188            strlcat

    Synopsis:    Concatenate 2 null-terminated strings, with length boundary.

Declaration:     function  strlcat(dest:  pchar;source:  pchar;l:  SizeInt)  :  pchar

    Visibility:   default

Description:     Adds MaxLen characters from Source to Dest, and adds a terminating null-character.  Re-
                turns Dest.

       Errors:   None.

    See also:    StrCat (1464   )


                Listing:  ./stringex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;


                Uses     s t r i n g s;


                {   Program       t o  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 (S t r L e n(P1  ) * 2 + 1 ) ;
                    P2 ^ : = # 0 ;  {  Z e r o  l e n g t h }
                    S t r C a t ( P2  ,P1  ) ;
                    S t r L C a t (P2  , P1  , 5 ) ;
                    W r i t e l n ( 'P2   =    ',P2  ) ;
                    S t r D i s p o s(eP2  )
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.189            strlcomp

    Synopsis:    Compare limited number of characters of 2 null-terminated strings

Declaration:     function  strlcomp(str1:  pchar;str2:  pchar;l:  SizeInt)  :  SizeInt

    Visibility:   default

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 (1465   ), StrIComp (1468   ), StrLIComp (1473   )


                Listing:  ./stringex/ex8.pp



                                                                                1470

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                Uses     s t r i n g s;


                {   Program       t o  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 ) ;
                    dec  ( l ) ;
                    W r i t e l n ( l , '  c h a r a c t e r sa r e  t h e  same   . ') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.190            strlcopy

    Synopsis:    Copy a null-terminated string, limited in length.

Declaration:     function  strlcopy(dest:  pchar;source:  pchar;maxlen:  SizeInt)  :  pchar

    Visibility:   default

Description:     Copies MaxLen characters from Source to Dest, and makes Dest a null terminated string.

       Errors:   No length checking is performed.

    See also:    StrCopy (1465   ), StrECopy (1466   )


                Listing:  ./stringex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                Uses     s t r i n g s;


                {   Program       t o  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 1 0  c h a r a c t e r so f  P   :   ' ,StrLCopy        (PP  ,P  , 1 0 ) ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.191            strlen

    Synopsis:    Length of a null-terminated string.



                                                                                1471

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Declaration:     function  strlen(p:  pchar)  :  sizeint

    Visibility:  default

Description:     Returns the length of the null-terminated string P.

       Errors:   None.

    See also:    StrNew (1474   )


                Listing:__./stringex/ex1.pp________________________________________________________________________________________*
 *___________

                Program       Example1       ;


                Uses     s t r i n g s;


                {   Program       t o  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.  }


                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 )  :   ', S t r L e n(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.192            StrLFmt

    Synopsis:    Format a string with given arguments, but with limited length.

Declaration:     function  StrLFmt(Buffer:  PCHar;Maxlen:  Cardinal;Fmt:  PChar;
                                           const  args:  Array  of  const)  :  Pchar
                function  StrLFmt(Buffer:  PCHar;Maxlen:  Cardinal;Fmt:  PChar;
                                           const  args:  Array  of  const;
                                           const  FormatSettings:  TFormatSettings)  :  Pchar

    Visibility:   default

Description:     StrLFmt will format fmt with Args, as the Format (1434   ) function does, and it will store
                maximally  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 (1434   ).

    See also:    StrFmt (1467   ), FmtStr (1433   ), Format (1434   ), FormatBuf (1440   )


                Listing:__./sysutex/ex81.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 8 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r F m t  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 ,'F o r  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___.____________________________________________________________________________________________________________*
 *___________

                                                                                1472

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.193            strlicomp

    Synopsis:    Compare limited number of characters in 2 null-terminated strings, ignoring case.

Declaration:     function  strlicomp(str1:  pchar;str2:  pchar;l:  SizeInt)  :  SizeInt

    Visibility:   default

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.


                For an example, see StrIComp (1468   )

       Errors:   None.

    See also:    StrLComp (1470   ), StrComp (1465   ), StrIComp (1468   )
                30.12.194            strlower

    Synopsis:    Convert null-terminated string to all-lowercase.

Declaration:     function  strlower(p:  pchar)  :  pchar

    Visibility:   default

Description:     Converts P to an all-lowercase string.  Returns P.

       Errors:   None.

    See also:    StrUpper (1485   )


                Listing:  ./stringex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                Uses     s t r i n g s;


                {   Program       t o  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___.____________________________________________________________________________________________________________*
 *___________


                                                                                1473

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.195            strmove

    Synopsis:    Move a null-terminated string to new location.

Declaration:     function  strmove(dest:  pchar;source:  pchar;l:  SizeInt)  :  pchar

    Visibility:   default

Description:     Copies  MaxLen  characters  from  Source  to  Dest.  No  terminating  null-character  is  copied.
                Returns Dest

       Errors:   None.

    See also:    StrLCopy (1471   ), StrCopy (1465   )


                Listing:  ./stringex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                Uses     s t r i n g s;


                {   Program       t o  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    :  P c h a r;


                 b e g i n
                    P2 :=  S t r A l l o c(S t r L e n(P1 ) + 1 ) ;
                    StrMove       (P2  , P1  ,S t r L e n(P1  ) + 1 ) ; {   P2 :=  P1   }
                    W r i t e l n ( 'P2   =    ',P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.196            strnew

    Synopsis:    Allocate room for new null-terminated string.

Declaration:     function  strnew(p:  pchar)  :  pchar

    Visibility:   default

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:    StrCopy (1465   ), StrDispose (1466   )


                Listing:  ./stringex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                Uses     s t r i n g s;


                {   Program       t o  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';

                                                                                1474

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                 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  c a n' 't   be   h a p p e n i n g. . .')
                    e l s e
                        w r i t e l n(  'P2   :   ' ,P2  ) ;
                    S t r D i s p o s(eP2  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.197            StrNextChar

    Synopsis:    Returns a pointer to the location of the next empty character in a null-terminated string

Declaration:     function  StrNextChar(const  Str:  PChar)  :  PChar

    Visibility:   default

Description:     StrNextChar returns a pointer to the null-character that terminates the string Str

       Errors:   if  Str is not properly terminated, an access violation may occur.
                30.12.198            StrPas

    Synopsis:    Convert a null-terminated string to an ansistring.

Declaration:     function  StrPas(Str:  PChar)  :  String

    Visibility:   default

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:    StrPCopy (1475   ), StrPLCopy (1476   )
                30.12.199            StrPCopy

    Synopsis:    Copy an ansistring to a null-terminated string.

Declaration:     function  StrPCopy(Dest:  PChar;Source:  String)  :  PChar

    Visibility:   default

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 (1476   ), StrPas (1475   )
                                                                                1475

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.200            StrPLCopy

    Synopsis:    Copy a limited number of characters from an ansistring to a null-terminated string.

Declaration:     function  StrPLCopy(Dest:  PChar;Source:  String;MaxLen:  SizeUInt)  :  PChar

    Visibility:   default

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.

    See also:    StrPCopy (1475   )
                30.12.201            strpos

    Synopsis:    Find position of one null-terminated substring in another.

Declaration:     function  strpos(str1:  pchar;str2:  pchar)  :  pchar

    Visibility:   default

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:    StrScan (1477   ), StrRScan (1476   )


                Listing:__./stringex/ex15.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 5;


                Uses     s t r i n g s;


                {   Program       t o  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   :  P c h a r =   ' i s' ;
                 b e g i n
                    W r i t e l n ( ' P o s i t i o no f   '' i s ''   i n P   :   ' ,l o n g i n t(S t r P o s(P , S)) -  L o n g *
 *i n t(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.202            strrscan

    Synopsis:    Find last occurrence of a character in a null-terminated string.

Declaration:     function  strrscan(p:  pchar;c:  Char)  :  pchar

    Visibility:   default

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.

                For an example, see StrScan (1477   ).

       Errors:   None.

    See also:    StrScan (1477   ), StrPos (1476   )



                                                                                1476

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.203            strscan

    Synopsis:    Find first occurrence of a character in a null-terminated string.

Declaration:     function  strscan(p:  pchar;c:  Char)  :  pchar

    Visibility:   default

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:    StrRScan (1476   ), StrPos (1476   )


                Listing:__./stringex/ex13.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 3;


                Uses     s t r i n g s;


                {   Program       t o  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 gf r o m  f i r s t  ' 's ' '  :   ' ,S t r S c a n(P ,s ) ) ;
                    W r i t e l n ( 'P ,   s t a r t i n gf r o m  l a s t  ' 's ' '  :   ' ,StrRScan      ( P ,s ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                30.12.204            StrToBool

    Synopsis:    Convert a string to a boolean value

Declaration:     function  StrToBool(const  S:  String)  :  Boolean

    Visibility:   default

Description:     StrToBool  will  convert  the  string  S  to  a  boolean  value.  The  string  S  can  contain  one  of
                'True', 'False' (case is ignored) or a numerical value.  If it contains a numerical value, 0 is
                converted to False, all other values result in True.  If the string S contains no valid boolean,
                then an EConvertError (1500   ) exception is raised.

       Errors:   On error, an EConvertError (1500   ) exception is raised.

    See also:    BoolToStr (1394   )
                30.12.205            StrToBoolDef

    Synopsis:    Convert string to boolean value, returning default in case of error

Declaration:     function  StrToBoolDef(const  S:  String;Default:  Boolean)  :  Boolean

    Visibility:   default

Description:     StrToBoolDef tries to convert the string S to a boolean value, and returns the boolean value
                in case of success.  In case S does not contain a valid boolean string, Default is returned.

    See also:    StrToBool (1477   ), TryStrToBool (1493   )



                                                                                1477

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.206            StrToCurr

    Synopsis:    Convert a string to a currency value

Declaration:     function  StrToCurr(const  S:  String)  :  Currency

    Visibility:   default

Description:     StrToCurr converts a string to a currency value and returns the value.  The string should
                contain a valid currency amount, without currency symbol.  If the conversion fails, an ECon-
                vertError (1500   ) exception is raised.

       Errors:   On error, an EConvertError (1500   ) exception is raised.

    See also:    CurrToStr (1400   ), StrToCurrDef (1478   )
                30.12.207            StrToCurrDef

    Synopsis:    Convert a string to a currency value, using a default value

Declaration:     function  StrToCurrDef(const  S:  String;Default:  Currency)  :  Currency

    Visibility:   default

Description:     StrToCurrDef  converts  a  string  to  a  currency  value  and  returns  the  value.   The  string
                should contain a valid currency amount,  without currency symbol.  If the conversion fails,
                the fallback Default value is returned.

       Errors:   On error, the Default value is returned.

    See also:    CurrToStr (1400   ), StrToCurr (1478   )
                30.12.208            StrToDate

    Synopsis:    Convert a date string to a TDateTime value.

Declaration:     function  StrToDate(const  S:  String)  :  TDateTime

    Visibility:   default

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 (1484   ), DateToStr (1404   ), TimeToStr (1489   )


                Listing:  ./sysutex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r T o D a t e f u n c t i o n}


                Uses      s y s u t i l;s
                                                                                1478

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                 P r o c e d u r eT 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.209            StrToDateDef

    Synopsis:    Convert string to date, returning a default value

Declaration:     function  StrToDateDef(const  S:  String;const  Defvalue:  TDateTime)
                                                     :  TDateTime

    Visibility:   default

Description:     StrToDateDef  tries  to  convert  the  string  S  to  a  valid  TDateTime  date  value,  and  returns
                DefValue if  S does not contain a valid date indication.

       Errors:   None.

    See also:    StrToDate (1478   ), TryStrToDate (1493   ), StrToTimeDef (1485   )
                30.12.210            StrToDateTime

    Synopsis:    Convert a date/time string to a TDateTime value.

Declaration:     function  StrToDateTime(const  S:  String)  :  TDateTime

    Visibility:   default

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.

    See also:    StrToDate (1478   ), StrToTime (1484   ), DateTimeToStr (1402   )


                Listing:  ./sysutex/ex20.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e StrToDateTime            f u n c t i o n}
                                                                                1479

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Uses      s y s u t i l;s


                 P r o c e d u r eT 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(' 05 -05 -1999  15:50         ' ) ;
                    T e s t S t r(' 5 - 5  1 3 : 3 0') ;
                    T e s t S t r(' 5  1 : 3 0PM  ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.211            StrToDateTimeDef

    Synopsis:    Convert string to date/time, returning a default value

Declaration:     function  StrToDateTimeDef(const  S:  String;const  Defvalue:  TDateTime)
                                                           :  TDateTime

    Visibility:   default

Description:     StrToDateTimeDef tries to convert the string S to a valid TDateTime date and time value,
                and returns DefValue if  S does not contain a valid date-time indication.

       Errors:   None.

    See also:    StrToTimeDef  (1485   ),  StrToDateDef  (1479   ),  TryStrToDateTime  (1494   ),  StrToDateTime
                (1479   )
                30.12.212            StrToFloat

    Synopsis:    Convert a string to a floating-point value.

Declaration:     function  StrToFloat(const  S:  String)  :  Extended
                function  StrToFloat(const  S:  String;
                                                const  FormatSettings:  TFormatSettings)  :  Extended

    Visibility:   default

Description:     StrToFloat  converts  the  string  S  to  a  floating  point  value.   S  should  contain  a  valid
                string representation of a floating point value (either in decimal or scientific notation).  The
                thousandseparator character may however not be used.

                Up to and including version 2.2.2 of the compiler, if the string contains a decimal value, then
                the decimal separator character can either be a '.'  or the value of the DecimalSeparator
                variable.

                As of version 2.3.1, the string may contain only the DecimalSeparator character.  The dot
                ('.')  can no longer be used instead of the DecimalSeparator.

       Errors:   If the string S doesn't contain a valid floating point string, then an exception will be raised.

    See also:    TextToFloat (1487   ), FloatToStr (1429   ), FormatFloat (1441   ), StrToInt (1482   )



                                                                                1480

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                Listing:__./sysutex/ex90.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 9 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r T o F l o a t f u n c t i o n}
                { $mode      o b j f p c}
                { $h  +  }


                Uses     S y s U t i l s;


                Const
                    N r V a l u e s=  5 ;
                    T e s t S t r :  A r r a y[ 1 . .N r V a l u e s]  o f  s t r i n g=
                                    ( '1 , 1 ' ,' -0 ,2  ' ,' 1 , 2E-4   ', '0  ', '1 E4  ' ) ;


                 P r o c e d u r eT e s t i t;


                Var
                    I   :  I n t e g e r;
                    E   :  E x t e n d e d;


                 b e g i n
                    W r i t e l n(' U s i n g D e c i m a l S e p a r a t o r:  ', D e c i m a l S e p a r a t o)r;
                    For    I : = 1  t o  N r V a l u e sdo
                        b e g i n
                        W r i t e l n('C o n v e r t i n g :  ' ,T e s t S t r[ i] ) ;
                       Try
                           E := S t r T o F l o a t(T e s t S t r[i] ) ;
                           W r i t e l n(' C o n v e r t e dv a l u e  :  ' ,E  ) ;
                        e x c e p t
                           On   E   :  E x c e p t i o ndo
                               W r i t e l n('E x c e p t i o nwhen     c o n v e r t i n g :  ' ,E . M e s s a g e) ;
                       end   ;
                       end   ;
                end   ;


                Begin
                    D e c i m a l S e p a r a t o:r=', ' ;
                    T e s t i t;
                    D e c i m a l S e p a r a t o:r='. ' ;
                    T e s t i t;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.213            StrToFloatDef

    Synopsis:    Convert a string to a float, with a default value.

Declaration:     function  StrToFloatDef(const  S:  String;const  Default:  Extended)
                                                      :  Extended
                function  StrToFloatDef(const  S:  String;const  Default:  Extended;
                                                     const  FormatSettings:  TFormatSettings)  :  Extended

    Visibility:   default

Description:     StrToFloatDef tries to convert the string S to a floating point value, and returns this value.
                If the conversion fails for some reason, the value Default is returned instead.

       Errors:   None.  On error, the Default value is returned.



                                                                                1481

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.214            StrToInt

    Synopsis:    Convert a string to an integer value.

Declaration:     function  StrToInt(const  s:  String)  :  Integer

    Visibility:   default

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 (1451   ), StrToIntDef (1483   )


                Listing:  ./sysutex/ex82.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 2;


                { $mode      o b j f p c}


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r T o I n t 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 ( S t r T o I n t('1234   ' ) ) ;
                    W r i t e l n ( S t r T o I n t('-1234    ' ) ) ;
                    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 dnumber       e n c o u n t e r e'd) ;
                    end  ;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.215            StrToInt64

    Synopsis:    Convert a string to an Int64 value.

Declaration:     function  StrToInt64(const  s:  String)  :  Int64

    Visibility:   default

Description:     StrToInt64  converts  the  string  S  to  a  Int64  value,  and  returns  this  value.   The  string
                can  only  contain  numerical  characters,  and  optionally  a  minus  sign  as  the  first  character.
                Whitespace is not allowed.

                Hexadecimal values (starting with the $ character) are supported.

       Errors:   On error, a EConvertError (1500   ) exception is raised.

    See also:    TryStrToInt64  (1495   ),  StrToInt64Def  (1483   ),  StrToInt  (1482   ),  TryStrToInt  (1494   ),  Str-
                ToIntDef (1483   )


                                                                                1482

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.216            StrToInt64Def

    Synopsis:    Convert a string to an Int64 value, with a default value

Declaration:     function  StrToInt64Def(const  S:  String;Default:  Int64)  :  Int64

    Visibility:   default

Description:     StrToInt64Def tries to convert the string S to a Int64 value, and returns this value.  If the
                conversion fails for some reason, the value Default is returned instead.

       Errors:   None.  On error, the Default value is returned.

    See also:    StrToInt64 (1482   ), TryStrToInt64 (1495   ), StrToInt (1482   ), TryStrToInt (1494   ), StrToIntDef
                (1483   )
                30.12.217            StrToIntDef

    Synopsis:    Convert a string to an integer value, with a default value.

Declaration:     function  StrToIntDef(const  S:  String;Default:  Integer)  :  Integer

    Visibility:   default

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 (1451   ), StrToInt (1482   )


                Listing:  ./sysutex/ex83.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 2;


                { $mode      o b j f p c}


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r T o I n t 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 ( S t r T o I n t D e(f'1234    ' , 0 ) ) ;
                    W r i t e l n ( S t r T o I n t D e(f'-1234    '  , 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 dnumber       e n c o u n t e r e'd) ;
                    end  ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                1483

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.218            StrToQWord

    Synopsis:    Convert a string to a QWord.

Declaration:     function  StrToQWord(const  s:  String)  :  QWord

    Visibility:   default

Description:     TryStrToQWord converts the string S to a valid QWord (unsigned 64-bit) value, and returns
                the result.

       Errors:   If the string S does not contain a valid QWord value, a EConvertError (1500   ) exception is
                raised.

    See also:    TryStrToQWord (1495   ), StrToQWordDef (1484   ), StrToInt64 (1482   ), StrToInt (1482   )
                30.12.219            StrToQWordDef

    Synopsis:    Try to convert a string to a QWord, returning a default value in case of failure.

Declaration:     function  StrToQWordDef(const  S:  String;Default:  QWord)  :  QWord

    Visibility:   default

Description:     StrToQWordDef tries to convert the string S to a valid QWord (unsigned 64-bit) value, and
                returns the result.  If the conversion fails, the function returns the value passed in Def.

    See also:    StrToQWord (1484   ), TryStrToQWord (1495   ), StrToInt64Def (1483   ), StrToIntDef (1483   )
                30.12.220            StrToTime

    Synopsis:    Convert a time string to a TDateTime value.

Declaration:     function  StrToTime(const  S:  String)  :  TDateTime

    Visibility:   default

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 (1478   ), StrToDateTime (1479   ), TimeToStr (1489   )


                Listing:  ./sysutex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 1;


                {   T h i s  p r o g r a m 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


                 P r o c e d u r eT 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



                                                                                1484

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                    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___.____________________________________________________________________________________________________________*
 *___________

                30.12.221            StrToTimeDef

    Synopsis:    Convert string to time, returning a default value

Declaration:     function  StrToTimeDef(const  S:  String;const  Defvalue:  TDateTime)
                                                     :  TDateTime

    Visibility:   default

Description:     StrToTimeDef tries to convert the string  S to a valid TDateTime time value,  and returns
                DefValue if  S does not contain a valid time indication.

       Errors:   None.

    See also:    StrToTime (1484   ), TryStrToTime (1495   ), StrToDateDef (1479   )
                30.12.222            strupper

    Synopsis:    Convert null-terminated string to all-uppercase

Declaration:     function  strupper(p:  pchar)  :  pchar

    Visibility:   default

Description:     Converts P to an all-uppercase string.  Returns P.

                For an example, see StrLower (1473   )

       Errors:   None.

    See also:    StrLower (1473   )
                30.12.223            Supports

    Synopsis:    Check whether a class or given interface supports an interface

Declaration:     function  Supports(const  Instance:  IInterface;const  IID:  TGUID;out  Intf)
                                              :  Boolean;    Overload
                function  Supports(const  Instance:  TObject;const  IID:  TGUID;out  Intf)
                                              :  Boolean;    Overload
                function  Supports(const  Instance:  IInterface;const  IID:  TGUID)  :  Boolean
                                            ;    Overload
                function  Supports(const  Instance:  TObject;const  IID:  TGUID)  :  Boolean
                                            ;    Overload
                function  Supports(const  AClass:  TClass;const  IID:  TGUID)  :  Boolean
                                            ;    Overload

    Visibility:   default

Description:     Supports checks whether Instance supports the interface identified by IID. It returns True
                if it is supported, False.  Optionally, a pointer to the interface is returned to Intf.



                                                                                1485

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
       Errors:   None.

    See also:    StringToGUID (1469   )
                30.12.224            SysErrorMessage

    Synopsis:    Format a system error message.

Declaration:     function  SysErrorMessage(ErrorCode:  Integer)  :  String

    Visibility:   default

Description:     SysErrorMessage returns a string that describes the operating system error code ErrorCode.

       Errors:   This routine may not be implemented on all platforms.

    See also:    EOSError (1503   )
                30.12.225            SystemTimeToDateTime

    Synopsis:    Convert a system time to a TDateTime value.

Declaration:     function  SystemTimeToDateTime(const  SystemTime:  TSystemTime)  :  TDateTime

    Visibility:   default

Description:     SystemTimeToDateTime  converts  a  TSystemTime  record  to  a  TDateTime  style  date/time
                indication.

       Errors:   None.

    See also:    DateTimeToSystemTime (1403   )


                Listing:  ./sysutex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   T h i s  p r o g r a m 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     S t  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___.____________________________________________________________________________________________________________*
 *___________


                                                                                1486

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.226            TextToFloat

    Synopsis:    Convert a buffer to a float value.

Declaration:     function  TextToFloat(Buffer:  PChar;var  Value:  Extended)  :  Boolean
                function  TextToFloat(Buffer:  PChar;var  Value:  Extended;
                                                 const  FormatSettings:  TFormatSettings)  :  Boolean
                function  TextToFloat(Buffer:  PChar;var  Value;ValueType:  TFloatValue)
                                                   :  Boolean
                function  TextToFloat(Buffer:  PChar;var  Value;ValueType:  TFloatValue;
                                                 const  FormatSettings:  TFormatSettings)  :  Boolean

    Visibility:   default

Description:     TextToFloat converts the string in Buffer to a floating point value.  Buffer should contain a
                valid stroing representation of a floating point value (either in decimal or scientific notation).
                If the buffer contains a decimal value, then the decimal separator character can either be a
                '.'  or the value of the DecimalSeparator variable.

                The function returns True if the conversion was successful.

       Errors:   If there is an invalid character in the buffer, then the function returns False

    See also:    StrToFloat (1480   ), FloatToStr (1429   ), FormatFloat (1441   )


                Listing:  ./sysutex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e T e x t T o F l o a tf u n c t i o n }
                { $mode      o b j f p c}
                { $h  +  }


                Uses     S y s U t i l s;


                Const
                    N r V a l u e s=  5 ;
                    T e s t S t r :  A r r a y[ 1 . .N r V a l u e s]  o f  p c h a r=
                                    ( '1 , 1 ' ,' -0 ,2  ' ,' 1 , 2E-4   ', '0  ', '1 E4  ' ) ;


                 P r o c e d u r eT e s t i t;


                Var
                    I   :  I n t e g e r;
                    E   :  E x t e n d e d;


                 b e g i n
                    W r i t e l n(' U s i n g D e c i m a l S e p a r a t o r:  ', D e c i m a l S e p a r a t o)r;
                    For    I : = 1  t o  N r V a l u e sdo
                        b e g i n
                        W r i t e l n('C o n v e r t i n g :  ' ,T e s t S t r[ i] ) ;
                        I f  TextToFloat        ( T e s t S t r[i ] ,E )  then
                           W r i t e l n(' C o n v e r t e dv a l u e  :  ' ,E )
                        e l s e
                           W r i t e l n(' U n a b l e t o  c o n v e r t v a l u e. ') ;
                       end   ;
                end   ;


                Begin
                    D e c i m a l S e p a r a t o:r=', ' ;



                                                                                1487

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                    T e s t i t;
                    D e c i m a l S e p a r a t o:r='. ' ;
                    T e s t i t;
                End___.____________________________________________________________________________________________________________*
 *___________

                30.12.227            Time

    Synopsis:    Returns the current time.

Declaration:     function  Time  :  TDateTime

    Visibility:   default

Description:     Time returns the current time in TDateTime format.  The date part of the TDateTimeValue
                is set to zero.

       Errors:   None.

    See also:    Now (1457   ), Date (1401   )


                Listing:  ./sysutex/ex23.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 3;


                {   T h i s  p r o g r a m 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.228            TimeStampToDateTime

    Synopsis:    Convert a TimeStamp value to a TDateTime value.

Declaration:     function  TimeStampToDateTime(const  TimeStamp:  TTimeStamp)  :  TDateTime

    Visibility:   default

Description:     TimeStampToDateTime converts TimeStamp to a TDateTime format variable.  It is the inverse
                operation of DateTimeToTimeStamp (1404   ).

       Errors:   None.

    See also:    DateTimeToTimeStamp (1404   ), TimeStampToMSecs (1489   )


                Listing:  ./sysutex/ex24.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 4;


                {   T h i s  p r o g r a m 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       ;



                                                                                1488

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________


                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 dp 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.229            TimeStampToMSecs

    Synopsis:    Converts a timestamp to a number of milliseconds.

Declaration:     function  TimeStampToMSecs(const  TimeStamp:  TTimeStamp)  :  comp

    Visibility:   default

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.

                For an example, see MSecsToTimeStamp (1456   ).

       Errors:   None.

    See also:    MSecsToTimeStamp (1456   ), TimeStampToDateTime (1488   )
                30.12.230            TimeToStr

    Synopsis:    Convert a TDateTime time to a string using a predefined format.

Declaration:     function  TimeToStr(Time:  TDateTime)  :  String

    Visibility:   default

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.


                Listing:  ./sysutex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   T h i s  p r o g r a m 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


                Begin
                    W r i t e l n ( 'The     c u r r e n tt i m e  i s  :   ' ,TimeToStr       (Time    ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________

                                                                                1489

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.231            Trim

    Synopsis:    Trim whitespace from the ends of a string.

Declaration:     function  Trim(const  S:  String)  :  String
                function  Trim(const  S:  widestring)  :  widestring

    Visibility:   default

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 (1490   ), TrimRight (1491   )


                Listing:  ./sysutex/ex84.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 4;


                {   T h i s  p r o g r a m 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 + }


                 P r o c e d u r eT 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 ) , '" ' ) ;
                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___.____________________________________________________________________________________________________________*
 *___________

                30.12.232            TrimLeft

    Synopsis:    Trim whitespace from the beginning of a string.

Declaration:     function  TrimLeft(const  S:  String)  :  String
                function  TrimLeft(const  S:  widestring)  :  widestring

    Visibility:   default

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 (1490   ), TrimRight (1491   )


                Listing:  ./sysutex/ex85.pp


                                                                                1490

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e T r i m L e f t f u n c t i o n }


                Uses      s y s u t i l;s
                { $H + }


                 P r o c e d u r eT 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.233            TrimRight

    Synopsis:    Trim whitespace from the end of a string.

Declaration:     function  TrimRight(const  S:  String)  :  String
                function  TrimRight(const  S:  widestring)  :  widestring

    Visibility:   default

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 (1490   ), TrimLeft (1490   )


                Listing:  ./sysutex/ex86.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e T r i m R i g h t f u n c t i o n}


                Uses      s y s u t i l;s
                { $H + }


                 P r o c e d u r eT 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(tS ) , '" ' ) ;
                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___.____________________________________________________________________________________________________________*
 *___________


                                                                                1491

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.234            TryEncodeDate

    Synopsis:    Try to encode a date, and indicate success.

Declaration:     function  TryEncodeDate(Year:  Word;Month:  Word;Day:  Word;
                                                     out  Date:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeDate will check the validity of the Year, Month and Day arguments, and if they
                are all valid, then they will be encoded as a TDateTime value and returned in D. The function
                will return True in this case.  If an inbvalid argument is passed, then False will be returned.

       Errors:   None.  If an error occurs during the encoding, False is returned.

    See also:    EncodeDate (1410   ), DecodeDateFully (1406   ), DecodeDate (1405   ), TryEncodeTime (1492   )
                30.12.235            TryEncodeTime

    Synopsis:    Try to encode a time, and indicate success.

Declaration:     function  TryEncodeTime(Hour:  Word;Min:  Word;Sec:  Word;MSec:  Word;
                                                     out  Time:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeTime will check the validity of the Hour, Min, Sec and MSec arguments, and will
                encode them in a TDateTime value which is returned in T. If the arguments are valid, then
                True is returned, otherwise False is returned.

       Errors:   None.  If an error occurs during the encoding, False is returned.

    See also:    EncodeTime (1410   ), DecodeTime (1406   ), TryEncodeDate (1492   )
                30.12.236            TryFloatToCurr

    Synopsis:    Try to convert a float value to a currency value and report on success.

Declaration:     function  TryFloatToCurr(const  Value:  Extended;var  AResult:  Currency)
                                                        :  Boolean

    Visibility:   default

Description:     TryFloatToCurr tries convert the Value floating point value to a Currency value.  If suc-
                cessful, the function returns True and the resulting currency value is returned in AResult.  It
                checks whether Value is in the valid range of currencies (determined by MinCurrency (1364   )
                and MaxCurrency (1364   )).  If not, False is returned.

       Errors:   If  Value is out of range, False is returned.

    See also:    FloatToCurr (1428   ), MinCurrency (1364   ), MaxCurrency (1364   )
                                                                                1492

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.237            TryStrToBool

    Synopsis:    Try to convert a string to a boolean value

Declaration:     function  TryStrToBool(const  S:  String;out  Value:  Boolean)  :  Boolean

    Visibility:   default

Description:     TryStrToBool  tries  to  convert  the  string  S  to  a  boolean  value,  and  returns  this  value  in
                Value.  In this case, the function returns True.  If  S does not contain a valid boolean string,
                the function returns False, and the contents of  Value is indetermined.

                Valid boolean string constants are in the FalseBoolStrs (1374   ) (for False values) and True-
                BoolStrs (1377   ) (for True values) variables.

    See also:    StrToBool (1477   ), StrToBoolDef (1477   )
                30.12.238            TryStrToCurr

    Synopsis:    Try to convert a string to a currency

Declaration:     function  TryStrToCurr(const  S:  String;var  Value:  Currency)  :  Boolean

    Visibility:   default

Description:     TryStrToCurr  converts  the  string  S  to  a  currency  value  and  returns  the  value  in  Value.
                The function returns True if it was successful, False if not.  This is contrary to StrToCurr
                (1478   ), which raises an exception when the conversion fails.

                The function takes into account locale information.

    See also:    StrToCurr (1478   ), TextToFloat (1487   )
                30.12.239            TryStrToDate

    Synopsis:    Try to convert a string with a date indication to a TDateTime value

Declaration:     function  TryStrToDate(const  S:  String;out  Value:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryStrToDate tries to convert the string S to a TDateTime date value, and stores the date
                in  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.

                The function returns True if the string contained a valid date indication, False otherwise.

    See also:    StrToDate  (1478   ),  StrToTime  (1484   ),  TryStrToTime  (1495   ),  TryStrToDateTime  (1494   ),
                DateToStr (1404   ), TimeToStr (1489   )


                                                                                1493

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.240            TryStrToDateTime

    Synopsis:    Try to convert a string with date/time indication to a TDateTime value

Declaration:     function  TryStrToDateTime(const  S:  String;out  Value:  TDateTime)
                                                           :  Boolean

    Visibility:   default

Description:     TryStrToDateTime tries to convert the string S to a TDateTime date and time value, and
                stores  the  result  in  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 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.

                The function returns True if the string contained a valid date and time indication,  False
                otherwise.

    See also:    TryStrToDate  (1493   ),  TryStrToTime  (1495   ),  StrToDateTime  (1479   ),  StrToTime  (1484   ),
                DateToStr (1404   ), TimeToStr (1489   )
                30.12.241            TryStrToFloat

    Synopsis:    Try to convert a string to a float.

Declaration:     function  TryStrToFloat(const  S:  String;var  Value:  Single)  :  Boolean
                function  TryStrToFloat(const  S:  String;var  Value:  Single;
                                                     const  FormatSettings:  TFormatSettings)  :  Boolean
                function  TryStrToFloat(const  S:  String;var  Value:  Double)  :  Boolean
                function  TryStrToFloat(const  S:  String;var  Value:  Double;
                                                     const  FormatSettings:  TFormatSettings)  :  Boolean

    Visibility:   default

Description:     TryStrToFloat tries to convert the string S to a floating point value, and stores the result in
                Value.  It returns True if the operation was succesful, and False if it failed.  This operation
                takes into account the system settings for floating point representations.

       Errors:   On error, False is returned.

    See also:    StrToFloat (1480   )
                30.12.242            TryStrToInt

    Synopsis:    Try to convert a string to an integer, and report on success.

Declaration:     function  TryStrToInt(const  s:  String;var  i:  Integer)  :  Boolean

    Visibility:   default

Description:     TryStrToInt tries to convert the string S to an integer, and returns True if this was succesful.
                In that case the converted integer is returned in I. If the conversion failed, (an invalid string,
                or the value is out of range) then False is returned.

       Errors:   None.  On error, False is returned.

    See also:    StrToInt (1482   ), TryStrToInt64 (1495   ), StrToIntDef (1483   ), StrToInt64 (1482   ), StrToInt64Def
                (1483   )



                                                                                1494

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.243            TryStrToInt64

    Synopsis:    Try to convert a string to an int64 value, and report on success.

Declaration:     function  TryStrToInt64(const  s:  String;var  i:  Int64)  :  Boolean

    Visibility:   default

Description:     TryStrToInt64 tries to convert the string S to a Int64 value, and returns this value in I if
                successful.  If the conversion was succesful, the function result is True, or False otherwise.
                The string can only contain numerical characters,  and optionally a minus sign as the first
                character.  Whitespace is not allowed.

                Hexadecimal values (starting with the $ character) are supported.

       Errors:   None.  On error, False is returned.

    See also:    StrToInt64 (1482   ), StrToInt64Def (1483   ), StrToInt (1482   ), TryStrToInt (1494   ), StrToIntDef
                (1483   )
                30.12.244            TryStrToQWord

    Synopsis:    Try to convert a string to a QWord value, and report on success

Declaration:     function  TryStrToQWord(const  s:  String;var  Q:  QWord)  :  Boolean

    Visibility:   default

Description:     TryStrToQWord tries to convert the string S to a valid QWord (unsigned 64-bit) value, and
                stores the result in I. If the conversion fails, the function returns False, else it returns True.

    See also:    StrToQWord (1484   ), StrToQWordDef (1484   ), TryStrToInt64 (1495   ), TryStrToInt (1494   )
                30.12.245            TryStrToTime

    Synopsis:    Try to convert a string with a time indication to a TDateTime value

Declaration:     function  TryStrToTime(const  S:  String;out  Value:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryStrToTime tries to convert the string S to a TDateTime time value, and stores the result
                in 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.

                The function returns True if the string contained a valid time indication, False otherwise.

    See also:    TryStrToDate  (1493   ),  TryStrToDateTime  (1494   ),  StrToDate  (1478   ),  StrToTime  (1484   ),
                DateToStr (1404   ), TimeToStr (1489   )
                30.12.246            UnhookSignal

    Synopsis:    UnHook a specified signal

Declaration:     procedure  UnhookSignal(RtlSigNum:  Integer;OnlyIfHooked:  Boolean)

    Visibility:   default

Description:     This function is declared for Kylix compatibility, but is not implemented.
                                                                                1495

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.247            UpperCase

    Synopsis:    Return an uppercase version of a string.

Declaration:     function  UpperCase(const  s:  String)  :  String

    Visibility:   default

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 (1383   ), LowerCase (1455   ), AnsiUpperCase (1391   )


                Listing:  ./sysutex/ex87.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e U p p e r C a s e 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___.____________________________________________________________________________________________________________*
 *___________

                30.12.248            VendorName

    Synopsis:    Returns the application vendor name.

Declaration:     function  VendorName  :  String

    Visibility:   default

Description:     VendorName returns the application vendor name.  This function does not do anything by
                itself, but uses the OnGetVendorName (1376   ) callback to get the application vendor name.

       Errors:   If OnGetVendorName (1376   ) is not set, an empty string is returned.

    See also:    OnGetVendorName (1376   ), TGetVendorNameEvent (1371   )
                30.12.249            WideCompareStr

    Synopsis:    Compare two widestrings (case sensitive)

Declaration:     function  WideCompareStr(const  s1:  WideString;const  s2:  WideString)
                                                        :  PtrInt

    Visibility:   default

Description:     WideCompareStr compares two widestrings and returns the following result:


                < 0 if  S1<S2.

                0 if  S1=S2.

                > 0  if  S1>S2.
                                                                                1496

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                The comparision takes into account wide characters,  i.e.  it takes care of strange accented
                characters.  Contrary to WideCompareText (1497   ), the comparision is case sensitive.

       Errors:   None.

    See also:    WideCompareText (1497   ), WideSameStr (1498   ), WideSameText (1499   )
                30.12.250            WideCompareText

    Synopsis:    Compare two widestrings (ignoring case).

Declaration:     function  WideCompareText(const  s1:  WideString;const  s2:  WideString)
                                                         :  PtrInt

    Visibility:   default

Description:     WideCompareStr compares two widestrings and returns the following result:


                < 0 if  S1<S2.

                0 if  S1=S2.

                > 0  if  S1>S2.


                The comparision takes into account wide characters,  i.e.  it takes care of strange accented
                characters.  Contrary to WideCompareStr (1496   ), the comparision is case insensitive.

       Errors:   None.

    See also:    WideCompareStr (1496   ), WideSameStr (1498   ), WideSameText (1499   )
                30.12.251            WideFmtStr

    Synopsis:    Widestring format

Declaration:     procedure  WideFmtStr(var  Res:  WideString;const  Fmt:  WideString;
                                                 const  args:  Array  of  const)
                procedure  WideFmtStr(var  Res:  WideString;const  Fmt:  WideString;
                                                 const  args:  Array  of  const;
                                                 const  FormatSettings:  TFormatSettings)

    Visibility:   default

Description:     WideFmtStr formats Args according to the format string in Fmt and returns the resulting
                string in Res.

    See also:    WideFormat (1497   ), WideFormatBuf (1498   ), Format (1434   )
                30.12.252            WideFormat

    Synopsis:    Format a wide string.

Declaration:     function  WideFormat(const  Fmt:  WideString;const  Args:  Array  of  const)
                                                 :  WideString
                function  WideFormat(const  Fmt:  WideString;const  Args:  Array  of  const;
                                                const  FormatSettings:  TFormatSettings)  :  WideString

    Visibility:   default
                                                                                1497

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
Description:     WideFormat does the same as Format (1434   ) but accepts as a formatting string a WideString.
                The resulting string is also a WideString.

                For more information about the used formatting characters, see the Format (1434   ) string.

    See also:    Format (1434   )
                30.12.253            WideFormatBuf

    Synopsis:    Format widestring in a buffer.

Declaration:     function  WideFormatBuf(var  Buffer;BufLen:  Cardinal;const  Fmt;
                                                     fmtLen:  Cardinal;const  Args:  Array  of  const)
                                                      :  Cardinal
                function  WideFormatBuf(var  Buffer;BufLen:  Cardinal;const  Fmt;
                                                     fmtLen:  Cardinal;const  Args:  Array  of  const;
                                                     const  FormatSettings:  TFormatSettings)  :  Cardinal

    Visibility:   default

Description:     WideFormatBuf calls simply WideFormat (1497   ) with Fmt (with length FmtLen bytes) and
                stores maximum BufLen bytes in the buffer buf.  It returns the number of copied bytes.

    See also:    WideFmtStr (1497   ), WideFormat (1497   ), Format (1434   ), FormatBuf (1440   )
                30.12.254            WideLowerCase

    Synopsis:    Change a widestring to all-lowercase.

Declaration:     function  WideLowerCase(const  s:  WideString)  :  WideString

    Visibility:   default

Description:     WideLowerCase 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 Unix-like platforms, a widestring manager must be installed for this function to work
                correctly.

       Errors:   None.

    See also:    WideUpperCase (1499   )
                30.12.255            WideSameStr

    Synopsis:    Check whether two widestrings are the same (case sensitive)

Declaration:     function  WideSameStr(const  s1:  WideString;const  s2:  WideString)
                                                   :  Boolean

    Visibility:   default

Description:     WideSameStr returns True if WideCompareStr (1496   ) returns 0 (zero), i.e.  when S1 and S2
                are the same string (taking into account case).

    See also:    WideSameText (1499   ),  WideCompareStr (1496   ),  WideCompareText (1497   ),  AnsiSameStr
                (1384   )
                                                                                1498

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.12.256            WideSameText

    Synopsis:    Check whether two widestrings are the same (ignoring case)

Declaration:     function  WideSameText(const  s1:  WideString;const  s2:  WideString)
                                                     :  Boolean

    Visibility:   default

Description:     WideSameText returns True if WideCompareText (1497   ) returns 0 (zero), i.e.  when S1 and
                S2 are the same string (taking into account case).

    See also:    WideSameStr (1498   ),  WideCompareStr (1496   ),  WideCompareText (1497   ),  AnsiSameText
                (1384   )
                30.12.257            WideUpperCase

    Synopsis:    Change a widestring to all-lowercase.

Declaration:     function  WideUpperCase(const  s:  WideString)  :  WideString

    Visibility:   default

Description:     WideUpperCase  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 Unix-like platforms, a widestring manager must be installed for this function to work
                correctly.

       Errors:   None.

    See also:    WideLowerCase (1498   )
                30.12.258            WrapText

    Synopsis:    Word-wrap a text.

Declaration:     function  WrapText(const  Line:  String;const  BreakStr:  String;
                                            const  BreakChars:  TSysCharSet;MaxCol:  Integer)  :  String
                function  WrapText(const  Line:  String;MaxCol:  Integer)  :  String

    Visibility:   default

Description:     WrapText does a wordwrap at column MaxCol of the string in Line.  It breaks the string
                only  at  characters  which  are  in  BreakChars  (default  whitespace  and  hyphen)  and  inserts
                then the string BreakStr (default the lineending character for the current OS).

    See also:    StringReplace (1469   )
                30.13            EAbort



                30.13.1          Description

                Abort  is  raised  by  the  Abort  (1377   )  procedure.   It  is  not  displayed  in  GUI  applications,
                and serves only to immediatly abort the current procedure, and return control to the main
                program loop.
                                                                                1499

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.14            EAbstractError



30.14.1          Description

EAbstractError is raised when an abstract error occurs, i.e.  when an unimplemented ab-
stract method is called.
30.15            EAccessViolation



30.15.1          Description

EAccessViolation  is  raised  when  the  OS  reports  an  Access  Violation,  i.e.   when  invalid
memory is accessed.
30.16            EAssertionFailed



30.16.1          Description

EAssertionFailed is raised when an application that is compiled with assertions, encounters
an invalid assertion.
30.17            EBusError



30.17.1          Description

EBusError is raised in case of a bus error.
30.18            EControlC



30.18.1          Description

EControlC is raised when the user has pressed CTRL-C in a console application.
30.19            EConvertError



30.19.1          Description

EConvertError is raised by the various conversion routines in the SysUtils unit.  The message
will contain more specific error information.
30.20            EDivByZero



30.20.1          Description

EDivByZero is used when the operating system or CPU signals a division by zero error.


                                                                1500

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.21            EExternal



30.21.1          Description

EExternal  is  the  base  exception  for  all  external  exceptions,  as  reported  by  the  CPU  or
operating system, as opposed to internal exceptions, which are raised by the program itself.
The SysUtils unit converts all operating system errors to descendents of  EExternal.
30.22            EExternalException



30.22.1          Description

EExternalException is raised when an external routine raises an exception.
30.23            EFormatError



30.23.1          Description

EformatError is raised in case of an error in one of the various Format (1434   ) functions.
30.24            EHeapMemoryError



30.24.1          Description

EHeapMemoryError is raised when an error occurs in heap (dynamically allocated) memory.
30.25            EInOutError



30.25.1          Description

EInOutError  is  raised  when  a  IO  routine  of  Free  Pascal  returns  an  error.   The  error  is
converted to an EInOutError only if the input/output checking feature of FPC is turned on.
The error code of the input/output operation is returned in ErrorCode (??  ).
30.26            EInterror



30.26.1          Description

EInterror  is  used  when  the  operating  system  or  CPU  signals  an  integer  operation  error,
e.g., an overflow.
30.27            EIntfCastError



30.27.1          Description

EIntfCastError is raised when an invalid interface cast is encountered.
                                                                1501

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.28            EIntOverflow



30.28.1          Description

EIntOverflow is used when the operating system or CPU signals a integer overflow error.
30.29            EInvalidCast



30.29.1          Description

EInvalidCast is raised when an invalid typecast error (using the as operator) is encountered.
30.30            EInvalidContainer



30.30.1          Description

EInvalidContainer is not yet used by Free Pascal, and is provided for Delphi compatibility
only.
30.31            EInvalidInsert



30.31.1          Description

EInvalidInsert  is  not  yet  used  by  Free  Pascal,  and  is  provided  for  Delphi  compatibility
only.
30.32            EInvalidOp



30.32.1          Description

EInvalidOp is raised when an invalid operation is encountered.
30.33            EInvalidPointer



30.33.1          Description

EInvalidPointer is raised when an invalid heap pointer is used.
30.34            EMathError



30.34.1          Description

EMathError  is  used  when  the  operating  system  or  CPU  signals  a  floating  point  overflow
error.



                                                                1502

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.35            ENoThreadSupport



30.35.1          Description

ENoThreadSupport is raised when some thread routines are invoked, and thread support was
not enabled when the program was compiled.
30.36            ENoWideStringSupport



30.36.1          Description

ENoWideStringSupport  is  the  exception  raised  when  a  run-time  233  occurs,  i.e.   when
widestring routines are called and the application does not contain widestring support.
30.37            EOSError



30.37.1          Description

EOSError  is  raised  when  some  Operating  System  call  fails.  The  ErrorCode  (??  )  property
contains the operating system error code.
30.38            EOutOfMemory



30.38.1          Description

EOutOfMemory occurs when memory can no longer be allocated on the heap.  An instance of
EOutOfMemory is allocated on the heap at program startup, so it is available when needed.
30.39            EOverflow



30.39.1          Description

EOverflow occurs when a float operation overflows.  (i.e.  result is too big to represent).
30.40            EPackageError



30.40.1          Description

EPackageError is not yet used by Free Pascal, and is provided for Delphi compatibility only.
30.41            EPrivilege



30.41.1          Description

EPrivilege is raised when the OS reports that an invalid instruction was executed.


                                                                1503

_______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___
30.42            EPropReadOnly



30.42.1          Description

EPropReadOnly is raised when an attempt is made to write to a read-only property.
30.43            EPropWriteOnly



30.43.1          Description

EPropWriteOnly is raised when an attempt is made to read from a write-only property.
30.44            ERangeError



30.44.1          Description

ERangeError is raised by the Free Pascal runtime library if range checking is on, and a range
check error occurs.
30.45            ESafecallException



30.45.1          Description

ESafecallException is not yet used by Free Pascal, and is provided for Delphi compatibility
only.
30.46            EStackOverflow



30.46.1          Description

EStackOverflow occurs when the stack has grown too big (e.g.  by infinite recursion).
30.47            EUnderflow



30.47.1          Description

EOverflow occurs when a float operation underflows (i.e.  result is too small to represent).
30.48            EVariantError



30.48.1          Description

EVariantError is raised by the internal variant routines.
30.48.2          Method  overview

__Page______Property____________Description___________________________________________________________________________________
__1505______CreateCode__________Create_an_instance_of_EVariantError_with_a_particular_error_code._____________________________
                                                                1504

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.48.3          EVariantError.CreateCode

    Synopsis:    Create an instance of  EVariantError with a particular error code.

Declaration:     constructor  CreateCode(Code:  LongInt)

    Visibility:   default

Description:     CreateCode calls the inherited constructor, and sets the ErrCode (??  ) property to Code.

    See also:    EVariantError.ErrCode (??  )
                30.49            Exception



                30.49.1          Description

                Exception is the base class for all exception handling routines in the RTL and FCL. While it
                is possible to raise an exception with any class descending from TObject, it is recommended
                to  use  Exception  as  the  basis  of  exception  class  objects:  the  Exception  class  introduces
                properties to associate a message and a help context with the exception being raised.  What
                is more, the SysUtils unit sets the necessary hooks to catch and display unhandled exceptions:
                in  such  cases,  the  message  displayed  to  the  end  user,  will  be  the  message  stored  in  the
                exception class.
                30.49.2          Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  1505      Create                        Constructs a new exception object with a given message.
                  1506      CreateFmt                     Constructs a new exception object and formats a new mes-
                                                          sage.
                  1507      CreateFmtHelp                 Constructs a new exception object and sets the help context
                                                          and formats the message
                  1506      CreateHelp                    Constructs a new exception object and sets the help context.
                  1506      CreateRes                     Constructs  a  new  exception  object  and  gets  the  message
                                                          from a resource.
                  1506      CreateResFmt                  Constructs a new exception object and formats the message
                                                          from a reasource.
                  1507      CreateResFmtHelp              Constructs a new exception object and sets the help context
                                                          and formats the message from a resource
                  1507      CreateResHelp                 Constructs a new exception object and sets the help context
                __________________________________________and_gets_the_message_from_a_resource_____________________________________*
 *___________
                30.49.3          Property  overview

                __Page______Property______________Access______Description__________________________________________________________*
 *___________
                  1507      HelpContext           rw          Help context associated with the exception.
                __1508______Message_______________rw__________Message_associated_with_the_exception._______________________________*
 *___________
                30.49.4          Exception.Create

    Synopsis:    Constructs a new exception object with a given message.

Declaration:     constructor  Create(const  msg:  String)

    Visibility:   public



                                                                                1505

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
       Errors:   Construction may fail if there is not enough memory on the heap.

    See also:    Exception.CreateFmt (1506   ), Exception.Message (1508   )
                30.49.5          Exception.CreateFmt

    Synopsis:    Constructs a new exception object and formats a new message.

Declaration:     constructor  CreateFmt(const  msg:  String;const  args:  Array  of  const)

    Visibility:   public

       Errors:   Construction may fail if there is not enough memory on the heap.

    See also:    Exception.Create (1505   ), Exception.Message (1508   ), Format (1434   )
                30.49.6          Exception.CreateRes

    Synopsis:    Constructs a new exception object and gets the message from a resource.

Declaration:     constructor  CreateRes(ResString:  PString)

    Visibility:   public

       Errors:   Construction may fail if there is not enough memory on the heap.

    See also:    Exception.Create  (1505   ),  Exception.CreateFmt  (1506   ),  Exception.CreateResFmt  (1506   ),
                Exception.Message (1508   )
                30.49.7          Exception.CreateResFmt

    Synopsis:    Constructs a new exception object and formats the message from a reasource.

Declaration:     constructor  CreateResFmt(ResString:  PString;const  Args:  Array  of  const)

    Visibility:   public

Description:     CreateResFmt  does  the  same  as  CreateFmt  (1506   ),  but  fetches  the  message  from  the  re-
                source string ResString.

       Errors:   Construction may fail if there is not enough memory on the heap.

    See also:    Exception.Create  (1505   ),  Exception.CreateFmt  (1506   ),  Exception.CreateRes  (1506   ),  Ex-
                ception.Message (1508   )
                30.49.8          Exception.CreateHelp

    Synopsis:    Constructs a new exception object and sets the help context.

Declaration:     constructor  CreateHelp(const  Msg:  String;AHelpContext:  Integer)

    Visibility:   public

Description:     CreateHelp does the same as the Create (1505   ) constructor, but additionally stores AHelpContext
                in the HelpContext (1507   ) property.

    See also:    Exception.Create (1505   )

                                                                                1506

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.49.9          Exception.CreateFmtHelp

    Synopsis:    Constructs a new exception object and sets the help context and formats the message

Declaration:     constructor  CreateFmtHelp(const  Msg:  String;const  Args:  Array  of  const;
                                                         AHelpContext:  Integer)

    Visibility:   public

Description:     CreateFmtHelp does the same as the CreateFmt (1506   ) constructor, but additionally stores
                AHelpContext in the HelpContext (1507   ) property.

    See also:    Exception.CreateFmt (1506   )
                30.49.10           Exception.CreateResHelp

    Synopsis:    Constructs a new exception object and sets the help context and gets the message from a
                resource

Declaration:     constructor  CreateResHelp(ResString:  PString;AHelpContext:  Integer)

    Visibility:   public

Description:     CreateResHelp does the same as the CreateRes (1506   ) constructor, but additionally stores
                AHelpContext in the HelpContext (1507   ) property.

    See also:    Exception.CreateRes (1506   )
                30.49.11           Exception.CreateResFmtHelp

    Synopsis:    Constructs a new exception object and sets the help context and formats the message from
                a resource

Declaration:     constructor  CreateResFmtHelp(ResString:  PString;
                                                              const  Args:  Array  of  const;
                                                              AHelpContext:  Integer)

    Visibility:   public

Description:     CreateResFmtHelp does the same as the CreateResFmt (1506   ) constructor, but additionally
                stores AHelpContext in the HelpContext (1507   ) property.

    See also:    Exception.CreateResFmt (1506   )
                30.49.12           Exception.HelpContext

    Synopsis:    Help context associated with the exception.

Declaration:     Property  HelpContext  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     HelpContext is the help context associated with the exception, and can be used to provide
                context-sensitive help when the exception error message is displayed.  It should be set in the
                exception constructor.

    See also:    Exception.CreateHelp (1506   ), Exception.Message (1508   )



                                                                                1507

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.49.13           Exception.Message

    Synopsis:    Message associated with the exception.

Declaration:     Property  Message  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Message provides additional information about the exception.  It is shown to the user in e.g.
                the ShowException (1462   ) routine, and should be set in the constructor when the exception
                is raised.

    See also:    Exception.Create (1505   ), Exception.HelpContext (1507   )
                30.50            EZeroDivide



                30.50.1          Description

                EZeroDivide occurs when a float division by zero occurs.
                30.51            IReadWriteSync



                30.51.1          Description

                IReadWriteSync is an interface for synchronizing read/write operations.  Writers are always
                guaranteed  to  have  exclusive  access:   readers  may  or  may  not  have  simultaneous  access,
                depending on the implementation.
                30.51.2          Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  1508      BeginRead           Start a read operation.
                  1509      BeginWrite          Start a write operation.
                  1509      EndRead             End a read operation
                __1509______EndWrite____________End_a_write_operation._____________________________________________________________*
 *___________
                30.51.3          IReadWriteSync.BeginRead

    Synopsis:    Start a read operation.

Declaration:     procedure  BeginRead

    Visibility:   default

Description:     BeginRead indicates that a read operation is about to be started.  If a write operation is
                in  progress,  then  the  call  will  block  untill  the  write  operation  finished.  Depending  on  the
                implementation the call may also block if another read operation is in progress.

                After BeginRead,  any write operation started with BeginWrite (1509   ) will block until En-
                dRead (1509   ) is called.

    See also:    IReadWriteSync.EndRead (1509   ), IReadWriteSync.BeginWrite (1509   ), IReadWriteSync.EndWrite
                (1509   )
                                                                                1508

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.51.4          IReadWriteSync.EndRead

    Synopsis:    End a read operation

Declaration:     procedure  EndRead

    Visibility:   default

Description:     EndRead signals the end of a read operation.  If there was any blocked write operation, that
                will be unblocked by a call to EndRead.

    See also:    IReadWriteSync.BeginRead (1508   ), IReadWriteSync.BeginWrite (1509   ), IReadWriteSync.EndWrite
                (1509   )
                30.51.5          IReadWriteSync.BeginWrite

    Synopsis:    Start a write operation.

Declaration:     function  BeginWrite  :  Boolean

    Visibility:   default

Description:     BeginWrite  signals  the  begin  of  a  write  operation.  This  call  will  block  if  any  other  read
                or write operation is currently in progress.  It will resumt only after all other read or write
                operations have finished.

    See also:    IReadWriteSync.EndRead (1509   ), IReadWriteSync.EndWrite (1509   ), IReadWriteSync.BeginRead
                (1508   )
                30.51.6          IReadWriteSync.EndWrite

    Synopsis:    End a write operation.

Declaration:     procedure  EndWrite

    Visibility:   default

Description:     EndWrite signals the end of a write operation.  After the call to EndWrite any other read
                or write operations can start.

    See also:    IReadWriteSync.EndRead (1509   ), IReadWriteSync.EndWrite (1509   ), IReadWriteSync.BeginRead
                (1508   )
                30.52            TMultiReadExclusiveWriteSynchronizer



                30.52.1          Description

                TMultiReadExclusiveWriteSynchronizer is a default implementation of the IReadWriteSync
                (1508   ) interface.  It uses a single mutex to protect access to the read/write resource, resulting
                in a single thread having access to the resource.



                                                                                1509

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.52.2          Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  1511      Beginread          Request read access to the resource
                  1510      Beginwrite         Request write access to the resource.
                  1510      Create             Create a new instance of the TMultiReadExclusiveWriteSynchronizer
                                               class
                  1510      Destroy            Destroys the TMultiReadExclusiveWriteSynchronizer instance
                  1511      Endread            Release read access to the resource
                __1511______Endwrite___________Release_write_access_to_the_resource________________________________________________*
 *___________
                30.52.3          TMultiReadExclusiveWriteSynchronizer.Create

    Synopsis:    Create a new instance of the TMultiReadExclusiveWriteSynchronizer class

Declaration:     constructor  Create;    Virtual

    Visibility:   public

Description:     Create creates a new instance of  TMultiReadExclusiveWriteSynchronizer.  It initializes
                a TRTLCriticalSection.

       Errors:   None.

    See also:    #rtl.system.TRTLCriticalSection (1201   )
                30.52.4          TMultiReadExclusiveWriteSynchronizer.Destroy

    Synopsis:    Destroys the TMultiReadExclusiveWriteSynchronizer instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Create  destroys  the  instance  of  TMultiReadExclusiveWriteSynchronizer.   It  frees  the
                TRTLCriticalSection it initialized, and calls the inherited destructor.

       Errors:   None.

    See also:    #rtl.system.TRTLCriticalSection (1201   )
                30.52.5          TMultiReadExclusiveWriteSynchronizer.Beginwrite

    Synopsis:    Request write access to the resource.

Declaration:     function  Beginwrite  :  Boolean

    Visibility:   public

Description:     Beginwrite is the implementation of  IReadWriteSync.BeginWrite.  It simply enters the
                critical section, and returns True.

       Errors:   None.

    See also:    IReadWriteSync.BeginWrite (1509   ), TMultiReadExclusiveWriteSynchronizer.EndWrite (1511   )

                                                                                1510

                _______________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________
                30.52.6          TMultiReadExclusiveWriteSynchronizer.Endwrite

    Synopsis:    Release write access to the resource

Declaration:     procedure  Endwrite

    Visibility:   public

Description:     Beginwrite  is  the  implementation  of  IReadWriteSync.EndWrite.   It  simply  leaves  the
                critical section.

       Errors:   None.

    See also:    IReadWriteSync.EndWrite (1509   ), TMultiReadExclusiveWriteSynchronizer.BeginWrite (1510   )
                30.52.7          TMultiReadExclusiveWriteSynchronizer.Beginread

    Synopsis:    Request read access to the resource

Declaration:     procedure  Beginread

    Visibility:   public

Description:     BeginRead  is  the  implementation  of  IReadWriteSync.BeginRead.  It  simply  attempts  to
                enter the critical section.

       Errors:   None.

    See also:    IReadWriteSync.BeginRead (1508   ), TMultiReadExclusiveWriteSynchronizer.EndRead (1511   )
                30.52.8          TMultiReadExclusiveWriteSynchronizer.Endread

    Synopsis:    Release read access to the resource

Declaration:     procedure  Endread

    Visibility:   public

Description:     EndRead is the implementation of  IReadWriteSync.EndRead.  It simply leaves the critical
                section.

       Errors:   None.

    See also:    IReadWriteSync.EndRead (1509   ), TMultiReadExclusiveWriteSynchronizer.BeginRead (1511   )
                                                                                1511


Chapter   31


Reference   for   unit   'typinfo'
31.1          Auxiliary  functions


Other typinfo related functions.



                                                       Table 31.1:



__Name_______________________________________Description___________________________________________________________________________*
 *____
  GetEnumName (1520   )                      Get an enumerated type element name
  GetEnumValue (1522   )                     Get ordinal number of an enumerated type, based on the name.
  GetEnumNameCount (1521   )                 Get number of elements in an enumerated type.
  GetTypeData (1535   )                      Skip type name and return a pointer to the type data
  SetToString (1543   )                      Convert a set to its string representation
  StringToSet (1545   )                      Convert a string representation of a set to a set



31.2          Getting  or  setting  property  values


Functions to set or set a property's value.
31.3          Examining  published  property  information


Functions for retrieving or examining property information
31.4          Used  units



31.5          Overview


The TypeInfo unit contains many routines which can be used for the querying of the Run-
Time  Type  Information  (RTTI)  which  is  generated  by  the  compiler  for  classes  that  are
compiled under the {$M+} switch.  This information can be used to retrieve or set property
values for published properties for totally unknown classes.  In particular, it can be used to



                                                            1512

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___

                                                       Table 31.2:

         __Name________________________________Description____________________________________________________________
           GetEnumProp (1522   )                Return the value of an enumerated type property
           GetFloatProp (1523   )               Return the value of a float property
           GetInt64Prop (1524   )               Return the value of an Int64 property
           GetMethodProp (1525   )              Return the value of a procedural type property
           GetObjectProp (1527   )              Return the value of an object property
           GetOrdProp (1529   )                 Return the value of an ordinal type property
           GetPropValue (1532   )               Return the value of a property as a variant
           GetSetProp (1532   )                 Return the value of a set property
           GetStrProp (1534   )                 Return the value of a string property
           GetWideStrProp (1535   )             Return the value of a widestring property
           GetVariantProp (1535   )             Return the value of a variant property
           SetEnumProp (1539   )                Set the value of an enumerated type property
           SetFloatProp (1539   )               Set the value of a float property
           SetInt64Prop (1540   )               Set the value of an Int64 property
           SetMethodProp (1541   )              Set the value of a procedural type property
           SetObjectProp (1541   )              Set the value of an object property
           SetOrdProp (1542   )                 Set the value of an ordinal type property
           SetPropValue (1542   )               Set the value of a property trhough a variant
           SetSetProp (1542   )                 Set the value of a set property
           SetStrProp (1543   )                 Set the value of a string property
           SetWideStrProp (1545   )             Set the value of a widestring property
           SetVariantProp (1544   )             Set the value of a variant property

stream classes.  The TPersistent class in the Classes unit is compiled in the {$M+} state and
serves as the base class for all classes that need to be streamed.

The unit should be compatible to the Delphi 5 unit with the same name.  The only calls that
are still missing are the Variant calls,  since Free Pascal does not support the variant type
yet.

The examples in this chapter use a rttiobj file, which contains an object that has a published
property of all supported types.  It also contains some auxiliary routines and definitions.
31.6          Constants,  types  and  variables



31.6.1         Constants

BooleanIdents  :  Array[Boolean]  of  String  =  ('False','True'  )


Names for boolean values


DotSep  :  String  =  '.'


Name separator character


OnGetPropValue  :  TGetPropValue  =  nil


This callback is set by the variants unit to enable reading of properties as a variant.  If set,
it is called by the GetPropValue (1532   ) function.



                                                                1513

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___

                                                       Table 31.3:

  _Name______________________________________Description______________________________________________________________________
    FindPropInfo (1519   )                    Getting property type information, With error checking.
    GetPropInfo (1530   )                     Getting property type information, No error checking.
    GetPropInfos (1530   )                    Find property information of a certain kind
    GetObjectPropClass (1528   )              Return the declared class of an object property
    GetPropList (1531   )                     Get a list of all published properties
    IsPublishedProp (1536   )                 Is a property published
    IsStoredProp (1536   )                    Is a property stored
    PropIsType (1537   )                      Is a property of a certain kind
    PropType (1538   )                        Return the type of a property

                                    Table 31.4:  Used units by unit 'typinfo'


                                                   __Name__________Page_____
                                                     sysutils      1356

OnGetVariantprop  :  TGetVariantProp  =  nil


This callback is set by the variants unit to enable reading of variant properties If set, it is
called by the GetVariantProp (1535   ) function.


OnSetPropValue  :  TSetPropValue  =  nil


This callback is set by the variants unit to enable writing of properties as a variant.  If set,
it is called by the SetPropValue (1542   ) function.


OnSetVariantprop  :  TSetVariantProp  =  nil


This callback is set by the variants unit to enable writing of variant properties.  If set, it is
called by the GetVariantProp (1535   ) function.


ptConst  =  3


Constant used in acces method


ptField  =  0


Property acces directly from field


ptStatic  =  1


Property acces via static method


ptVirtual  =  2


Property acces via virtual method
                                                                1514

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___
tkAny  =  [Low  (  TTypeKind  )  ..High  (  TTypeKind  )  ]


Any property type


tkMethods  =  [tkMethod]


Only method properties.  (event handlers)


tkProperties  =  tkAny  -  tkMethods  -  [tkUnknown]


Real properties.  (not methods)


tkString  =  tkSString


Alias for the tsSString enumeration value
31.6.2         Types

PPropInfo  =  ^TPropInfo


Pointer to TPropInfo (1518   ) record


PPropList  =  ^TPropList


Pointer to TPropList (1518   )


PPTypeInfo  =  ^PTypeInfo


Pointer to PTypeInfo (1515   ) pointer


PTypeData  =  ^TTypeData


Pointer to TTypeData (1518   ) record.


PTypeInfo  =  ^TTypeInfo


Pointer to TTypeInfo (1518   ) record


ShortStringBase  =


ShortStringBase is the base definition of a short string.


TFloatType  =  (ftSingle,ftDouble,ftExtended,ftComp,ftCurr)


The size of a float type.


TGetPropValue  =  function(Instance:  TObject;const  PropName:  String;
                                         PreferStrings:  Boolean)  :  Variant


The callback function must return the property with name PropName of instance Instance.
If  PreferStrings is true,  it should favour converting the property to a string value.  The
function needs to return the variant with the property value.



                                                                1515

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___

                          Table 31.5:  Enumeration values for type TFloatType


                                      __Value______________Explanation__________________
                                        ftComp             Comp-type float
                                        ftCurr             Currency-type float
                                        ftDouble           Double-sized float
                                        ftExtended         Extended-size float
                                        ftSingle           Single-sized float

TGetVariantProp  =  function(Instance:  TObject;PropInfo:  PPropInfo)
                                              :  Variant


The  callback  function  must  return  the  variant  property  with  name  PropName  of  instance
Instance.


TIntfFlag  =  (ifHasGuid,ifDispInterface,ifDispatch,ifHasStrGUID)
                            Table 31.6:  Enumeration values for type TIntfFlag


                       __Value___________________Explanation___________________________________________
                         ifDispatch              Interface is a dispatch interface
                         ifDispInterface         Interface is a dual dispatch interface
                         ifHasGuid               Interface has GUID identifier
                         ifHasStrGUID            Interface has a string GUID identifier
Type of interface.


TIntfFlags=  Set  of  (ifDispatch,ifDispInterface,ifHasGuid,ifHasStrGUID)


Set of TIntfFlag (1516   ).


TIntfFlagsBase=  Set  of  (ifDispatch,ifDispInterface,ifHasGuid,
                                       ifHasStrGUID)


Set of TIntfFlag (1516   ).


TMethodKind  =  (mkProcedure,mkFunction,mkConstructor,mkDestructor,
                        mkClassProcedure,mkClassFunction)


Method type description


TOrdType  =  (otSByte,otUByte,otSWord,otUWord,otSLong,otULong)


If the property is and ordinal type, then TOrdType determines the size and sign of the ordinal
type:


TParamFlag  =  (pfVar,pfConst,pfArray,pfAddress,pfReference,pfOut)


TParamFlag describes a parameter.



                                                                1516

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___

                        Table 31.7:  Enumeration values for type TMethodKind


                                  _Value_________________________Explanation__________________
                                    mkClassFunction              Class function
                                    mkClassProcedure             Class procedure
                                    mkConstructor                Class constructor
                                    mkDestructor                 Class Desctructor
                                    mkFunction                   Function method
                                    mkProcedure                  Procedure method.

                           Table 31.8:  Enumeration values for type TOrdType


                                  _Value____________Explanation_______________________________
                                    otSByte          Signed byte
                                    otSLong          Signed longint
                                    otSWord          Signed word
                                    otUByte          Unsigned byte
                                    otULong          Unsigned longing (Cardinal)
                                    otUWord          Unsigned word

TParamFlags=  Set  of  (pfAddress,pfArray,pfConst,pfOut,pfReference,pfVar)


The kind of parameter for a method


TProcInfoProc  =  procedure(PropInfo:  PPropInfo)  of  object


Property info callback method


TPropData  =  packed  record
   PropCount  :  Word;
   PropList  :  record
      _alignmentdummy  :  ptrint;
   end;
end
The TPropData record is not used, but is provided for completeness and compatibility with
Delphi.


TPropInfo  =  packed  record
   PropType  :  PTypeInfo;
   GetProc  :  Pointer;
   SetProc  :  Pointer;
   StoredProc  :  Pointer;
   Index  :  Integer;
   Default  :  LongInt;
   NameIndex  :  SmallInt;
   PropProcs  :  Byte;
   Name  :  ShortString;
end

                                                                1517

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___

                          Table 31.9:  Enumeration values for type TParamFlag


            __Value_______________Explanation_____________________________________________________________________
              pfAddress           Parameter is passed by address
              pfArray             Parameter is an array parameter
              pfConst             Parameter is a const parameter (i.e.  cannot be modified)
              pfOut               Parameter is a string parameter
              pfReference         Parameter is passed by reference
              pfVar               Parameter is a var parameter (passed by reference)

The TPropInfo record describes one published property of a class.  The property information
of a class are stored as an array of  TPropInfo records.

The Name field is stored not with 255 characters, but with just as many characters as required
to store the name.


TPropList  =  Array[0..65535]  of  PPropInfo


Array of property information pointers


TSetPropValue  =  procedure(Instance:  TObject;const  PropName:  String;
                                          const  Value:  Variant)


The callback function must set the property with name PropName of instance Instance to
Value.


TSetVariantProp  =  procedure(Instance:  TObject;PropInfo:  PPropInfo;
                                              const  Value:  Variant)


The  callback  function  must  set  the  variant  property  with  name  PropName  of  instance  to
Value.


TTypeData  =  packed  record
end
If the typeinfo kind is tkClass, then the property information follows the UnitName string,
as an array of TPropInfo (1518   ) records.


TTypeInfo  =  record
   Kind  :  TTypeKind;
   Name  :  ShortString;
end
The TypeInfo function returns a pointer to a TTypeInfo record.

Note  that  the  Name  field  is  stored  with  as  much  bytes  as  needed  to  store  the  name,  it  is
not padded to 255 characters.  The type data immediatly follows the TTypeInfo record as a
TTypeData (1518   ) record.

                                                                1518

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________

                                         Table 31.10:  Enumeration values for type TTypeKind


                                              __Value___________________Explanation______________________________
                                                tkArray                  Array property.
                                                tkAString                Ansistring property.
                                                tkBool                   Boolean property.
                                                tkChar                   Char property.
                                                tkClass                  Class property.
                                                tkDynArray               Dynamical array property.
                                                tkEnumeration            Enumeration type property.
                                                tkFloat                  Float property.
                                                tkInt64                  Int64 property.
                                                tkInteger                Integer property.
                                                tkInterface              Interface property.
                                                tkInterfaceRaw           Raw interface property.
                                                tkLString                Longstring property.
                                                tkMethod                 Method property.
                                                tkObject                 Object property.
                                                tkQWord                  QWord property.
                                                tkRecord                 Record property.
                                                tkSet                    Set property.
                                                tkSString                Shortstring property.
                                                tkUnknown                Unknown property type.
                                                tkVariant                Variant property.
                                                tkWChar                  Widechar property.
                                                tkWString                Widestring property.

                TTypeKind  =  (tkUnknown,tkInteger,tkChar,tkEnumeration,tkFloat,tkSet,
                                     tkMethod,tkSString,tkLString,tkAString,tkWString,tkVariant,
                                     tkArray,tkRecord,tkInterface,tkClass,tkObject,tkWChar,
                                     tkBool,tkInt64,tkQWord,tkDynArray,tkInterfaceRaw)


                Type of a property.


                TTypeKinds=  Set  of  (tkArray,tkAString,tkBool,tkChar,tkClass,tkDynArray,
                                                 tkEnumeration,tkFloat,tkInt64,tkInteger,tkInterface,
                                                 tkInterfaceRaw,tkLString,tkMethod,tkObject,tkQWord,
                                                 tkRecord,tkSet,tkSString,tkUnknown,tkVariant,
                                                 tkWChar,tkWString)


                Set of TTypeKind (1519   ) enumeration.
                31.7          Procedures  and  functions



                31.7.1         FindPropInfo

    Synopsis:    Return property information by property name.

Declaration:     function  FindPropInfo(Instance:  TObject;const  PropName:  String)
                                                     :  PPropInfo
                function  FindPropInfo(AClass:  TClass;const  PropName:  String)  :  PPropInfo



                                                                                1519

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
    Visibility:  default

Description:     FindPropInfo examines the published property information of a class and returns a pointer
                to the property information for property PropName.  The class to be examined can be specified
                in one of two ways:


                AClass    a class pointer.

                Instance     an instance of the class to be investigated.


                If the property does not exist, a EPropertyError exception will be raised.  The GetPropInfo
                (1530   ) function has the same function as the FindPropInfo function, but returns Nil if the
                property does not exist.

       Errors:   Specifying an invalid property name in PropName will result in an EPropertyError excep-
                tion.

    See also:    GetPropInfo (1530   ), GetPropList (1531   ), GetPropInfos (1530   )


                Listing:  ./typinfex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 1 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e F i n d P r o p I n f of u n c t i o n }


                { $mode      o b j f p c}


                 u s e s
                    r t t i o b j,t y p i n f o,s y s u t i l s;



                Var
                    O   :  TMyTestObject          ;
                    PT   :   PTypeData       ;
                    PI   :   P P r o p I n f o;
                    I ,J   :   L o n g i n t;
                    PP   :   P P r o p L i s t;
                    p r I  :   P P r o p I n f;o


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  F i n d P r o p I n f(oO ,' B o o l e a n F i e l'd) ;
                    W r i t e l n(' F i n d P r o p I n f(oI n s t a n c,eB o o l e a n F i e l)d :   ' ,PI  ^ .Name    ) ;
                    PI :=  F i n d P r o p I n f(oO .C l a s s T y p e,'B y t e F i e l d') ;
                    W r i t e l n(' F i n d P r o p I n f(oC l a s s,B y t e F i e l d)            :  ' ,PI  ^ .Name    ) ;
                    Write       ( ' F i n d P r o p I n f(oC l a s s,N o n E x i s t i n g P r o)p :  ' ) ;
                    Try
                       PI  :=  F i n d P r o p I n f(oO, 'N o n E x i s t i n g P r o'p) ;
                    e x c e p t
                       On   E  :  E x c e p t i o ndo
                           W r i t e l n(' Caught      e x c e p t i o n" ' ,E . ClassName       , '"   w i t h m e s s a g e  :  '*
 * ,E . M e s s a g e) ;
                    end  ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.2         GetEnumName

    Synopsis:    Return name of enumeration constant.



                                                                                1520

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
Declaration:     function  GetEnumName(TypeInfo:  PTypeInfo;Value:  Integer)  :  String

    Visibility:  default

Description:     GetEnumName scans the type information for the enumeration type described by TypeInfo
                and returns the name of the enumeration constant for the element with ordinal value equal
                to Value.

                If Value is out of range, the first element of the enumeration type is returned.  The result is
                lowercased, but this may change in the future.

                This can be used in combination with GetOrdProp to stream a property of an enumerated
                type.

       Errors:   No check is done to determine whether TypeInfo really points to the type information for
                an enumerated type.

    See also:    GetOrdProp (1529   ), GetEnumValue (1522   )


                Listing:  ./typinfex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e GetEnumName         ,  GetEnumValue           f u n c t i o*
 * n s}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    TI   :   P T y p e I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    TI :=  G e t P r o p I n f(oO , 'MyEnumField         ') ^ .PropType      ;
                    W r i t e l n('GetEnumName                            :   ' ,GetEnumName        ( TI  ,Ord  ( O . MyEnumField  *
 *      ) ) ) ;
                    W r i t e l n(' GetEnumValue         ( m e f i r s t)  :  ' ,GetEnumName        ( TI  ,GetEnumValue         ( T*
 *I , ' m e f i r s t') ) ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.3         GetEnumNameCount

    Synopsis:    Return number of names in an enumerated type

Declaration:     function  GetEnumNameCount(enum1:  PTypeInfo)  :  SizeInt

    Visibility:   default

Description:     GetEnumNameCount returns the number of values (names) in the enumerated type, described
                by enum1

       Errors:   No checking is done to see whether Enum1 is really type information of an enumerated type.

    See also:    GetEnumValue (1522   ), GetEnumName (1520   )


                                                                                1521

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.4         GetEnumProp

    Synopsis:    Return the value of an enumeration type property.

Declaration:     function  GetEnumProp(Instance:  TObject;const  PropName:  String)  :  String
                function  GetEnumProp(Instance:  TObject;const  PropInfo:  PPropInfo)
                                                   :  String

    Visibility:   default

Description:     GetEnumProp returns the value of an property of an enumerated type and returns the name
                of the enumerated value for the objetc Instance.  The property whose value must be returned
                can be specified by its property info in PropInfo or by its name in PropName

       Errors:   No check is done to determine whether PropInfo really points to the property information
                for an enumerated type.  Specifying an invalid property name in PropName will result in an
                EPropertyError exception.

    See also:    SetEnumProp (1539   ), GetOrdProp (1529   ), GetStrProp (1534   ), GetInt64Prop (1524   ), Get-
                MethodProp (1525   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )


                Listing:  ./typinfex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e GetEnumProp          f u n c t i o n }


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;
                    TI   :   P T y p e I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  G e t P r o p I n f(oO , 'MyEnumField         ') ;
                    TI :=  PI  ^ .PropType      ;
                    W r i t e l n('Enum      p r o p e r t y      :  ' ) ;
                    W r i t e l n(' V a l u e                                 :  ' ,GetEnumName         (TI  ,Ord   (O  .MyEnumFiel*
 *d         ) ) ) ;
                    W r i t e l n(' Get    (name    )                         :  ' ,GetEnumProp         (O , ' MyEnumField        '*
 * ) ) ;
                    W r i t e l n(' Get    ( p r o p i n f o)                 :  ' ,GetEnumProp         (O , PI  ) ) ;
                    SetEnumProp        ( O , 'MyEnumField         ', ' m e F i r s t') ;
                    W r i t e l n(' S e t  (name    ,m e F i r s t)           :  ' ,GetEnumName         (TI  ,Ord   (O  .MyEnumFiel*
 *d         ) ) ) ;
                    SetEnumProp        ( O ,PI  , 'meSecond       ') ;
                    W r i t e l n(' S e t  ( p r o p i n f o,meSecond     )  :   ' ,GetEnumName         (TI  ,Ord   (O  .MyEnumFiel*
 *d         ) ) ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.5         GetEnumValue

    Synopsis:    Get ordinal value for enumerated type by name

Declaration:     function  GetEnumValue(TypeInfo:  PTypeInfo;const  Name:  String)  :  Integer

    Visibility:   default



                                                                                1522

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
Description:     GetEnumValue scans the type information for the enumeration type described by TypeInfo
                and returns the ordinal value for the element in the enumerated type that has identifier Name.
                The identifier is searched in a case-insensitive manner.

                This can be used to set the value of enumerated properties from a stream.

                For an example, see GetEnumName (1520   ).

       Errors:   If  Name is not found in the list of enumerated values, then -1 is returned.  No check is done
                whether TypeInfo points to the type information for an enumerated type.

    See also:    GetEnumName (1520   ), SetOrdProp (1542   )
                31.7.6         GetFloatProp

    Synopsis:    Return value of floating point property

Declaration:     function  GetFloatProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Extended
                function  GetFloatProp(Instance:  TObject;const  PropName:  String)
                                                     :  Extended

    Visibility:   default

Description:     GetFloatProp returns the value of the float property described by PropInfo or with name
                Propname for the object Instance.  All float types are converted to extended.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                float property of  Instance.  Specifying an invalid property name in PropName will result in
                an EPropertyError exception.

    See also:    SetFloatProp (1539   ), GetOrdProp (1529   ), GetStrProp (1534   ), GetInt64Prop (1524   ), Get-
                MethodProp (1525   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )


                Listing:  ./typinfex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t F l o a t P r o pf u n c t i o n }


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' R e a l  p r o p e r t y:   ' ) ;
                    PI :=  G e t P r o p I n f(oO , 'R e a l F i e l d') ;
                    W r i t e l n(' V a l u e                     :  ' ,O . R e a l F i e l d) ;
                    W r i t e l n(' Get    (name    )             :  ' ,G e t F l o a t P r o(pO , 'R e a l F i e l d') ) ;
                    W r i t e l n(' Get    ( p r o p i n f o)     :  ' ,G e t F l o a t P r o(pO ,PI  ) ) ;
                    S e t F l o a t P r o(pO , 'R e a l F i e l d',s y s t e m.P i ) ;
                    W r i t e l n(' S e t  (name    ,p i )        :  ' ,O . R e a l F i e l d) ;
                    S e t F l o a t P r o(pO ,PI  ,exp   ( 1 ) ) ;
                    W r i t e l n(' S e t  ( p r o p i n f o,e)  :   ' ,O . R e a l F i e l d) ;
                    W r i t e l n(' E x t e n d e d p r o p e r t y:   ' ) ;
                                                                                1523

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                    PI :=  G e t P r o p I n f(oO , 'E x t e n d e d F i e l'd) ;
                    W r i t e l n(' V a l u e                     :  ' ,O . E x t e n d e d F i e l)d;
                    W r i t e l n(' Get    (name    )             :  ' ,G e t F l o a t P r o(pO , 'E x t e n d e d F i e l'd) ) ;
                    W r i t e l n(' Get    ( p r o p i n f o)     :  ' ,G e t F l o a t P r o(pO ,PI  ) ) ;
                    S e t F l o a t P r o(pO , 'E x t e n d e d F i e l'd,s y s t e m.P i ) ;
                    W r i t e l n(' S e t  (name    ,p i )        :  ' ,O . E x t e n d e d F i e l)d;
                    S e t F l o a t P r o(pO ,PI  ,exp   ( 1 ) ) ;
                    W r i t e l n(' S e t  ( p r o p i n f o,e)  :   ' ,O . E x t e n d e d F i e l)d;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.7         GetInt64Prop

    Synopsis:    return value of an Int64 property

Declaration:     function  GetInt64Prop(Instance:  TObject;PropInfo:  PPropInfo)  :  Int64
                function  GetInt64Prop(Instance:  TObject;const  PropName:  String)  :  Int64

    Visibility:   default

Description:Remark:Publishing of Int64 properties is not yet supported by Free Pascal.  This function is provided
                for Delphi compatibility only at the moment.

                GetInt64Prop returns the value of the property of type Int64 that is described by PropInfo
                or with name Propname for the object Instance.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                Int64 property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception

    See also:    SetInt64Prop (1540   ), GetOrdProp (1529   ), GetStrProp (1534   ), GetFloatProp (1523   ), Get-
                MethodProp (1525   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )


                Listing:  ./typinfex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t I n t 6 4 P r o pf u n c t i o n }


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' I n t 6 4 p r o p e r t y :   ') ;
                    PI :=  G e t P r o p I n f(oO , 'I n t 6 4 F i e l d') ;
                    W r i t e l n(' V a l u e                     :  ' ,O . I n t 6 4 F i e l)d;
                    W r i t e l n(' Get    (name    )             :  ' ,G e t I n t 6 4 P r o(pO , 'I n t 6 4 F i e l d') ) ;
                    W r i t e l n(' Get    ( p r o p i n f o)     :  ' ,G e t I n t 6 4 P r o(pO ,PI  ) ) ;
                    S e t I n t 6 4 P r o(pO , 'I n t 6 4 F i e l d', 1 2 3 4 5 ) ;
                    W r i t e l n(' S e t  (name    , 1 2 3 4 5 )      :  ' ,O . I n t 6 4 F i e l d) ;
                    S e t I n t 6 4 P r o(pO ,PI  , 5 4 3 2 1 ) ;
                    W r i t e l n(' S e t  ( p r o p i n f o, 5 4 3 2 1 )  :' ,O . I n t 6 4 F i e l)d;



                                                                                1524

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.8         GetInterfaceProp

    Synopsis:    Return interface-typed property

Declaration:     function  GetInterfaceProp(Instance:  TObject;const  PropName:  String)
                                                           :  IInterface
                function  GetInterfaceProp(Instance:  TObject;PropInfo:  PPropInfo)
                                                           :  IInterface

    Visibility:   default

Description:     GetInterfaceProp returns the interface which the property described by PropInfo or with
                name Propname points to for object Instance.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                method property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    SetInterfaceProp  (1540   ),  GetOrdProp  (1529   ),  GetStrProp  (1534   ),  GetFloatProp  (1523   ),
                GetInt64Prop (1524   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )
                31.7.9         GetMethodProp

    Synopsis:    Return value of a method property

Declaration:     function  GetMethodProp(Instance:  TObject;PropInfo:  PPropInfo)  :  TMethod
                function  GetMethodProp(Instance:  TObject;const  PropName:  String)
                                                      :  TMethod

    Visibility:   default

Description:     GetMethodProp  returns  the  method  the  property  described  by  PropInfo  or  with  name
                Propname for object Instance.  The return type TMethod is defined in the SysUtils unit as:


                TMethod  =  packed  record
                    Code,  Data:  Pointer;
                end;


                Data points to the instance of the class with the method Code.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                method property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    SetMethodProp  (1541   ),  GetOrdProp  (1529   ),  GetStrProp  (1534   ),  GetFloatProp  (1523   ),
                GetInt64Prop (1524   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )


                Listing:  ./typinfex/ex6.pp


                                                                                1525

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___
______________________________________________________________________________________________________________________________
program       e x a m p l e 6;


{   T h i s  p r o g r a m d e m o n s t r a t e st h e GetMethodProp            f u n c t i o n}


{ $mode      o b j f p c}


 u s e s r t t i o b j,t y p i n f o,s y s u t i l s;


Type
    T N o t i f y O b j e c t=  C l a s s(T O b j e c t)
       P r o c e d u r e N o t i f i c a t i o n(1S e n d e r :  T O b j e c t) ;
       P r o c e d u r e N o t i f i c a t i o n(2S e n d e r :  T O b j e c t) ;
    end  ;


 P r o c e d u r eT N o t i f y O b j e c.tN o t i f i c a t i o n(1S e n d e r:  T O b j e c t) ;


 b e g i n
    Write    ( 'R e c e i v e d n o t i f i c a t i o n1  o f  o b j e c t  w i t h c l a s s:   ') ;
    W r i t e l n(S e n d e r.ClassName       ) ;
end   ;


 P r o c e d u r eT N o t i f y O b j e c.tN o t i f i c a t i o n(2S e n d e r:  T O b j e c t) ;


 b e g i n
    Write    ( 'R e c e i v e d n o t i f i c a t i o n2  o f  o b j e c t  w i t h c l a s s:   ') ;
    W r i t e l n(S e n d e r.ClassName       ) ;
end   ;


Var
    O   :  TMyTestObject          ;
    PI   :   P P r o p I n f o;
   NO    :   T N o t i f y O b j e c;t
   M    :  TMethod     ;


 P r o c e d u r eP r i n t M e t h o d( Const    M    :  TMethod     ) ;


 b e g i n
    I f  (M  .Data   = P o i n t e r(NO  ) )  Then
        I f  (M . Code  =  P o i n t e r(@ T N o t i f y O b j e c.tN o t i f i c a t i o n)1) then
           W r i t e l n(' N o t i f i c a t i o n'1)
        e l s e I f  ( M . Code  =  P o i n t e r(@ T N o t i f y O b j e c.tN o t i f i c a t i o)n)2 then
           W r i t e l n(' N o t i f i c a t i o n'2)
        e l s e
           b e g i n
           Write    ( 'Unknown       method      a d r e s s ( d a t a: ' ) ;
           Write    ( h e x S t r(L o n g i n t(M .d a t a) , 8 ) ) ;
           W r i t e l n(' ,c o d e :' , h e x s t r(L o n g i n t(M .Code   ) , 8 ) ,' ) ') ;
           end  ;
end   ;



 b e g i n
    O := TMyTestObject          . C r e a t e;
   NO  :=  T N o t i f y O b j e c.tC r e a t e;
    O . N o t i f y E v e n:t=@NO   .N o t i f i c a t i o n;1
    PI :=  G e t P r o p I n f(oO , 'N o t i f y E v e n t') ;
    W r i t e l n(' Method      p r o p e r t y :  ' ) ;
    Write    ( 'N o t i f y i n g                                  :   ') ;



                                                                1526

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                    O . N o t i f y;
                    Write    ( 'Get    ( name   )                                  :   ') ;
                   M  := GetMethodProp          (O  ,' N o t i f y E v e n't) ;
                    P r i n t M e t h o(dM ) ;
                    Write    ( 'N o t i f y i n g                                  :   ') ;
                    O . N o t i f y;
                    Write    ( 'Get    ( p r o p i n f o)                          :   ') ;
                   M  := GetMethodProp          (O  ,PI  ) ;
                    P r i n t M e t h o(dM ) ;
                   M  := TMethod     ( @NO   .N o t i f i c a t i o n)2;
                    S e t M e t h o d P r o(pO, ' N o t i f y E v e n't,M ) ;
                    Write    ( 'S e t  ( name   , N o t i f i c a t i o n)2        :   ') ;
                   M  := GetMethodProp          (O  ,PI  ) ;
                    P r i n t M e t h o(dM ) ;
                    Write    ( 'N o t i f y i n g                                  :   ') ;
                    O . N o t i f y;
                    Write    ( 'S e t  ( p r o p i n f o,N o t i f i c a t i o n)1 :   ') ;
                   M  := TMethod     ( @NO   .N o t i f i c a t i o n)1;
                    S e t M e t h o d P r o(pO, PI  ,M ) ;
                   M  := GetMethodProp          (O  ,PI  ) ;
                    P r i n t M e t h o(dM ) ;
                    Write    ( 'N o t i f y i n g                                  :   ') ;
                    O . N o t i f y;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.10          GetObjectProp

    Synopsis:    Return value of an object-type property.

Declaration:     function  GetObjectProp(Instance:  TObject;const  PropName:  String)
                                                      :  TObject
                function  GetObjectProp(Instance:  TObject;const  PropName:  String;
                                                     MinClass:  TClass)  :  TObject
                function  GetObjectProp(Instance:  TObject;PropInfo:  PPropInfo)  :  TObject
                function  GetObjectProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                     MinClass:  TClass)  :  TObject

    Visibility:   default

Description:     GetObjectProp returns the object which the property described by  PropInfo with name
                Propname points to for object Instance.

                If  MinClass is specified, then if the object is not descendent of class MinClass, then Nil is
                returned.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                method property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    SetMethodProp  (1541   ),  GetOrdProp  (1529   ),  GetStrProp  (1534   ),  GetFloatProp  (1523   ),
                GetInt64Prop (1524   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )


                Listing:  ./typinfex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5;

                                                                                1527

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t O b j e c t P r o pf u n c t i o n}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;
                    NO1  , NO2    :  TNamedObject          ;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    NO1  :=  TNamedObject         .C r e a t e;
                    NO1  . ObjectName       :=  ' F i r s t named      o b j e c t';
                    NO2  :=  TNamedObject         .C r e a t e;
                    NO2  . ObjectName       :=  ' S e c o n d named     o b j e c t' ;
                    O . O b j F i e l:d= NO1  ;
                    W r i t e l n(' O b j e c t p r o p e r t y :  ' ) ;
                    PI :=  G e t P r o p I n f(oO , 'O b j F i e l d') ;
                    Write    ( 'P r o p e r t y c l a s s         :  ' ) ;
                    W r i t e l n(G e t O b j e c t P r o p C l a(sOs, 'O b j F i e l d') .ClassName       ) ;
                    Write    ( 'V a l u e                         :  ' ) ;
                    W r i t e l n( (O .O b j F i e l d a s  TNamedObject         ) .ObjectName        ) ;
                    Write    ( 'Get    ( name   )                 :  ' ) ;
                    W r i t e l n( (G e t O b j e c t P r o(pO, 'O b j F i e l d')  As    TNamedObject         ) .ObjectName       *
 * ) ;
                    Write    ( 'Get    ( p r o p i n f o)         :  ' ) ;
                    W r i t e l n( (G e t O b j e c t P r o(pO,PI  , T O b j e c t) a s   TNamedObject         ) .ObjectName       *
 * ) ;
                    S e t O b j e c t P r o(pO, ' O b j F i e l d',NO2   ) ;
                    Write    ( 'S e t  ( name   ,NO2   )          :  ' ) ;
                    W r i t e l n( (O .O b j F i e l d a s  TNamedObject         ) .ObjectName        ) ;
                    S e t O b j e c t P r o(pO, PI  ,NO1   ) ;
                    Write    ( 'S e t  ( p r o p i n f o,NO1  )  :   ' ) ;
                    W r i t e l n( (O .O b j F i e l d a s  TNamedObject         ) .ObjectName        ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.11          GetObjectPropClass

    Synopsis:    Return class of property.

Declaration:     function  GetObjectPropClass(Instance:  TObject;const  PropName:  String)
                                                              :  TClass

    Visibility:   default

Description:     GetObjectPropClass returns the declared class of the property with name PropName.  This
                may not be the actual class of the property value.

                For an example, see GetObjectProp (1527   ).

       Errors:   No checking is done whether Instance is non-nil.  Specifying an invalid property name in
                PropName will result in an EPropertyError exception.

    See also:    SetMethodProp  (1541   ),  GetOrdProp  (1529   ),  GetStrProp  (1534   ),  GetFloatProp  (1523   ),
                GetInt64Prop (1524   )


                                                                                1528

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.12          GetOrdProp

    Synopsis:    Get the value of an ordinal property

Declaration:     function  GetOrdProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Int64
                function  GetOrdProp(Instance:  TObject;const  PropName:  String)  :  Int64

    Visibility:   default

Description:     GetOrdProp returns the value of the ordinal property described by PropInfo or with name
                PropName  for  the  object  Instance.   The  value  is  returned  as  a  longint,  which  should  be
                typecasted to the needed type.

                Ordinal properties that can be retrieved include:


                Integers and subranges of integers                    The value of the integer will be returned.

                Enumerated types and subranges of enumerated types                                    The ordinal value of the enu-
                       merated type will be returned.

                Sets   If the base type of the set has less than 31 possible values.  If a bit is set in the return
                       value, then the corresponding element of the base ordinal class of the set type must be
                       included in the set.


       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                ordinal property of  Instance Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    SetOrdProp (1542   ), GetStrProp (1534   ), GetFloatProp (1523   ), GetInt64Prop (1524   ), Get-
                MethodProp (1525   ), GetSetProp (1532   ), GetObjectProp (1527   ), GetEnumProp (1522   )


                Listing:  ./typinfex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e GetOrdProp          f u n c t i o n}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' B o o l e a n p r o p e r t y      :  ' ) ;
                    W r i t e l n(' V a l u e                          :  ' ,O . B o o l e a n F i e l)d;
                    W r i t e l n(' Ord  ( V a l u e)                  :  ' ,Ord   (O . B o o l e a n F i e l)d) ;
                    W r i t e l n(' Get    (name    )                  :  ' ,GetOrdProp        (O  , 'B o o l e a n F i e l'd) ) ;
                    PI :=  G e t P r o p I n f(oO , 'B o o l e a n F i e l'd) ;
                    W r i t e l n(' Get    ( p r o p i n f o)          :  ' ,GetOrdProp        (O  ,PI  ) ) ;
                    S e t O r d P r o(pO , ' B o o l e a n F i e l'd,Ord  ( F a l s e) ) ;
                    W r i t e l n(' S e t  (name    ,f a l s e)        :  ' ,O . B o o l e a n F i e l)d;
                    S e t O r d P r o(pO , PI , Ord  ( True   ) ) ;
                    W r i t e l n(' S e t  ( p r o p i n f o,t r u e)  :  ' ,O . B o o l e a n F i e l)d;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________


                                                                                1529

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.13          GetPropInfo

    Synopsis:    Return property type information, by property name.

Declaration:     function  GetPropInfo(TypeInfo:  PTypeInfo;const  PropName:  String)
                                                   :  PPropInfo
                function  GetPropInfo(TypeInfo:  PTypeInfo;const  PropName:  String;
                                                 AKinds:  TTypeKinds)  :  PPropInfo
                function  GetPropInfo(Instance:  TObject;const  PropName:  String;
                                                 AKinds:  TTypeKinds)  :  PPropInfo
                function  GetPropInfo(Instance:  TObject;const  PropName:  String)
                                                   :  PPropInfo
                function  GetPropInfo(AClass:  TClass;const  PropName:  String;
                                                 AKinds:  TTypeKinds)  :  PPropInfo
                function  GetPropInfo(AClass:  TClass;const  PropName:  String)  :  PPropInfo

    Visibility:   default

Description:     GetPropInfo returns a pointer to the TPropInfo record for a the PropName property of a
                class.  The class to examine can be specified in one of three ways:


                Instance     An instance of the class.

                AClass     A class pointer to the class.

                TypeInfo       A pointer to the type information of the class.


                In each of these three ways, if AKinds is specified, if the property has TypeKind which is not
                included in Akinds, Nil will be returned.

                For an example, see most of the other functions.

       Errors:   If the property PropName does not exist, Nil is returned.

    See also:    GetPropInfos (1530   ), GetPropList (1531   )
                31.7.14          GetPropInfos

    Synopsis:    Return a list of published properties.

Declaration:     procedure  GetPropInfos(TypeInfo:  PTypeInfo;PropList:  PPropList)

    Visibility:   default

Description:     GetPropInfos stores pointers to the property information of all published properties of a
                class  with  class  info  TypeInfo  in  the  list  pointed  to  by  Proplist.  The  PropList  pointer
                must point to a memory location that contains enough space to hold all properties of the
                class and its parent classes.

       Errors:   No checks are done to see whether PropList points to a memory area that is big enough to
                hold all pointers.

    See also:    GetPropInfo (1530   ), GetPropList (1531   )


                Listing:  ./typinfex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 1 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t P r o p I n f o sf u n c t i o n }

                                                                                1530

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                 u s e s
                    r t t i o b j,t y p i n f o;



                Var
                    O   :  TMyTestObject          ;
                    PT   :   PTypeData       ;
                    PI   :   P T y p e I n f o;
                    I ,J   :   L o n g i n t;
                    PP   :   P P r o p L i s t;
                    p r I  :   P P r o p I n f;o


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  O . C l a s s I n f;o
                    PT :=  GetTypeData        ( PI  ) ;
                    W r i t e l n(' P r o p e r t yCount      :   ',PT  ^ . P r o p C o u n t) ;
                    GetMem      ( PP  ,PT  ^ .P r o p C o u n t*S i z e O f(P o i n t e r) ) ;
                    G e t P r o p I n f o(sPI , PP  ) ;
                    For    I : = 0  t o  PT  ^ .PropCount      -1    do
                        b e g i n
                       With     PP  ^ [i ] ^  do
                           b e g i n
                           Write    ( 'P r o p e r t y ' , i+ 1 : 3 ,' :  ' ,name    : 3 0 ) ;
                           w r i t e l n('    Type   :   ' ,TypeNames       [ t y p i n f o.PropType     ( O ,Name    ) ] ) ;
                           end  ;
                       end   ;
                    FreeMem     ( PP  ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.15          GetPropList

    Synopsis:    Return a list of a certain type of published properties.

Declaration:     function  GetPropList(TypeInfo:  PTypeInfo;TypeKinds:  TTypeKinds;
                                                 PropList:  PPropList;Sorted:  Boolean)  :  LongInt
                function  GetPropList(TypeInfo:  PTypeInfo;out  PropList:  PPropList)
                                                   :  SizeInt
                function  GetPropList(AObject:  TObject;out  PropList:  PPropList)  :  Integer

    Visibility:   default

Description:     GetPropList stores pointers to property information of the class with class info TypeInfo
                for properties of kind TypeKinds in the list pointed to by Proplist.  PropList must contain
                enough space to hold all properties.

                The function returns the number of pointers that matched the criteria and were stored in
                PropList.

       Errors:   No checks are done to see whether PropList points to a memory area that is big enough to
                hold all pointers.

    See also:    GetPropInfos (1530   ), GetPropInfo (1530   )


                Listing:  ./typinfex/ex13.pp

                                                                                1531

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 1 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t P r o p L i s tf u n c t i o n }


                 u s e s
                    r t t i o b j,t y p i n f o;



                Var
                    O   :  TMyTestObject          ;
                    PT   :   PTypeData       ;
                    PI   :   P T y p e I n f o;
                    I ,J   :   L o n g i n t;
                    PP   :   P P r o p L i s t;
                    p r I  :   P P r o p I n f;o


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  O . C l a s s I n f;o
                    PT :=  GetTypeData        ( PI  ) ;
                    W r i t e l n(' T o t a l p r o p e r t y Count     :   ' ,PT  ^ .P r o p C o u n t) ;
                    GetMem      ( PP  ,PT  ^ .P r o p C o u n t*S i z e O f(P o i n t e r) ) ;
                    J := G e t P r o p L i s(tPI  ,O r d i n a l T y p e,sPP  ) ;
                    W r i t e l n(' O r d i n a l p r o p e r t yCount      :   ', J ) ;
                    For    I : = 0  t o  J -1   do
                        b e g i n
                       With     PP  ^ [i ] ^  do
                           b e g i n
                           Write    ( 'P r o p e r t y ' , i+ 1 : 3 ,' :  ' ,name    : 3 0 ) ;
                           w r i t e l n('    Type   :   ' ,TypeNames       [ t y p i n f o.PropType     ( O ,Name    ) ] ) ;
                           end  ;
                       end   ;
                    FreeMem     ( PP  ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.16          GetPropValue

    Synopsis:    Get property value as a string.

Declaration:     function  GetPropValue(Instance:  TObject;const  PropName:  String)
                                                     :  Variant
                function  GetPropValue(Instance:  TObject;const  PropName:  String;
                                                   PreferStrings:  Boolean)  :  Variant

    Visibility:   default

Description:     Due to missing Variant support, GetPropValue is not yet implemented.  The declaration
                is provided for compatibility with Delphi.

       Errors:
                31.7.17          GetSetProp

    Synopsis:    Return the value of a set property.
                                                                                1532

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
Declaration:     function  GetSetProp(Instance:  TObject;const  PropName:  String)  :  String
                function  GetSetProp(Instance:  TObject;const  PropName:  String;
                                               Brackets:  Boolean)  :  String
                function  GetSetProp(Instance:  TObject;const  PropInfo:  PPropInfo;
                                               Brackets:  Boolean)  :  String

    Visibility:  default

Description:     GetSetProp returns the contents of a set property as a string.  The property to be returned
                can be specified by it's name in PropName or by its property information in PropInfo.

                The  returned  set  is  a  string  representation  of  the  elements  in  the  set  as  returned  by  Set-
                ToString (1543   ).  The Brackets option can be used to enclose the string representation in
                square brackets.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                ordinal property of  Instance Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    SetSetProp  (1542   ),  GetStrProp  (1534   ),  GetFloatProp  (1523   ),  GetInt64Prop  (1524   ),  Get-
                MethodProp (1525   )


                Listing:  ./typinfex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t S e t P r o p f u n c t i o n}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 F u n c t i o nS e t A s S t r i n g( ASet     :  TMyEnums      )  :   S t r i n g;


                Var
                    i   :  TmyEnum     ;


                 b e g i n
                    r e s u l t:= ' ' ;
                    For    i := m e f i r s t t o  m e t h i r d do
                        I f  i  i n  ASet     then
                           b e g i n
                           I f  ( R e s u l t<> ' ' )  then
                               R e s u l t:= R e s u l+t ' ,' ;
                           R e s u l t:= R e s u l t+MyEnumNames        [ i ] ;
                           end  ;
                end   ;


                Var
                    S   :  TMyEnums      ;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    O . S e t F i e l:d= [ m e f i r s t,meSecond      ,meThird      ] ;
                    W r i t e l n(' S e t  p r o p e r t y      :  ' ) ;



                                                                                1533

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                    W r i t e l n(' V a l u e                                          :  ' ,S e t A s S t r i n(gO . S e t F i e l*
 * d) ) ;
                    W r i t e l n(' Ord  ( V a l u e)                                  :  ' ,L o n g i n t(O . S e t F i e l d) ) ;
                    W r i t e l n(' Get    (name    )                                  :  ' ,G e t S e t P r o p(O, ' S e t F i e l*
 * d') ) ;
                    PI :=  G e t P r o p I n f(oO , 'S e t F i e l d') ;
                    W r i t e l n(' Get    ( p r o p i n f o)                          :  ' ,G e t S e t P r o p(O, PI  ,f a l s e)*
 * ) ;
                    S : = [m e F i r s t,meThird     ] ;
                    S e t O r d P r o(pO , ' S e t F i e l d',I n t e g e r(S ) ) ;
                    Write    ( 'S e t  ( name   , [ m e f i r s t,m e t h i r d] )   : ') ;
                    W r i t e l n(S e t A s S t r i n(gO . S e t F i e l d) ) ;
                    S : = [meSecond      ] ;
                    S e t O r d P r o(pO , PI , I n t e g e r(S ) ) ;
                    Write    ( 'S e t  ( p r o p i n f o, [meSecond      ] )       :   ') ;
                    W r i t e l n(S e t A s S t r i n(gO . S e t F i e l d) ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.18          GetStrProp

    Synopsis:    Return the value of a string property.

Declaration:     function  GetStrProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Ansistring
                function  GetStrProp(Instance:  TObject;const  PropName:  String)  :  String

    Visibility:   default

Description:     GetStrProp returns the value of the string property described by PropInfo or with name
                PropName for object Instance.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                string property of Instance.  Specifying an invalid property name in PropName will result in
                an EPropertyError exception.

    See also:    SetStrProp  (1543   ),  SetWideStrProp  (1545   ),  GetOrdProp  (1529   ),  GetFloatProp  (1523   ),
                GetInt64Prop (1524   ), GetMethodProp (1525   )


                Listing:  ./typinfex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e G e t S t r P r o p f u n c t i o n}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  G e t P r o p I n f(oO , 'A n s i S t r i n g F i e l'd) ;
                    W r i t e l n(' S t r i n g p r o p e r t y :  ' ) ;
                    W r i t e l n(' V a l u e                                 :  ' ,O . A n s i S t r i n g F i e l)d;
                    W r i t e l n(' Get    (name    )                         :  ' , G e t S t r P r o(pO , 'A n s i S t r i n g F *
 *i e l'd) ) ;
                    W r i t e l n(' Get    ( p r o p i n f o)                 :  ' , G e t S t r P r o(pO ,PI  ) ) ;
                    S e t S t r P r o(pO , ' A n s i S t r i n g F i e l'd,'F i r s t') ;
                                                                                1534

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                    W r i t e l n(' S e t  (name    ,' ' F i r s t'' )           :   ' ,O . A n s i S t r i n g F i e l)d;
                    S e t S t r P r o(pO , PI , ' S e c o n d') ;
                    W r i t e l n(' S e t  ( p r o p i n f o,'' S e c o n d'' )  :   ' ,O . A n s i S t r i n g F i e l)d;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.19          GetTypeData

    Synopsis:    Return a pointer to type data, based on type information.

Declaration:     function  GetTypeData(TypeInfo:  PTypeInfo)  :  PTypeData

    Visibility:   default

Description:     GetTypeData returns a pointer to the TTypeData record that follows after the TTypeInfo
                record pointed to by TypeInfo.  It essentially skips the Kind and Name fields in the TTypeInfo
                record.

       Errors:   None.
                31.7.20          GetVariantProp

    Synopsis:    Return the value of a variant property.

Declaration:     function  GetVariantProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Variant
                function  GetVariantProp(Instance:  TObject;const  PropName:  String)
                                                        :  Variant

    Visibility:   default

Description:     Due to mising Variant support, the GetVariantProp function is not yet implemented.  Pro-
                vided for Delphi compatibility only.

       Errors:

    See also:    SetVariantProp (1544   )
                31.7.21          GetWideStrProp

    Synopsis:    Read a widestring property

Declaration:     function  GetWideStrProp(Instance:  TObject;PropInfo:  PPropInfo)
                                                        :  WideString
                function  GetWideStrProp(Instance:  TObject;const  PropName:  String)
                                                        :  WideString

    Visibility:   default

Description:     GetWideStrProp  returns  the  value  of  the  widestring  property  described  by  PropInfo  or
                with name PropName for object Instance.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                widestring  property  of  Instance.   Specifying  an  invalid  property  name  in  PropName  will
                result in an EPropertyError exception.

    See also:    GetStrProp  (1534   ),  SetWideStrProp  (1545   ),  GetOrdProp  (1529   ),  GetFloatProp  (1523   ),
                GetInt64Prop (1524   ), GetMethodProp (1525   )



                                                                                1535

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.22          IsPublishedProp

    Synopsis:    Check whether a published property exists.

Declaration:     function  IsPublishedProp(Instance:  TObject;const  PropName:  String)
                                                         :  Boolean
                function  IsPublishedProp(AClass:  TClass;const  PropName:  String)
                                                         :  Boolean

    Visibility:   default

Description:     IsPublishedProp  returns  true  if  a  class  has  a  published  property  with  name  PropName.
                The class can be specfied in one of two ways:


                AClass     A class pointer to the class.

                Instance     An instance of the class.


       Errors:   No checks are done to ensure Instance or AClass are valid pointers.  Specifying an invalid
                property name in PropName will result in an EPropertyError exception.

    See also:    IsStoredProp (1536   ), PropIsType (1537   )


                Listing:  ./typinfex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s P u b l i s h e d P r o pf u n c t i o n}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' P r o p e r t y t e s t s      :   ' ) ;
                    Write    ( 'I s P u b l i s h e d P r o(pO, B o o l e a n F i e l)d        :   ') ;
                    W r i t e l n(I s P u b l i s h e d P r o(pO, 'B o o l e a n F i e l'd) ) ;
                    Write    ( 'I s P u b l i s h e d P r o(pC l a s s,B o o l e a n F i e l)d :   ') ;
                    W r i t e l n(I s P u b l i s h e d P r o(pO.C l a s s T y p e,' B o o l e a n F i e l'd) ) ;
                    Write    ( 'I s P u b l i s h e d P r o(pO, S o m e F i e l)d              :   ') ;
                    W r i t e l n(I s P u b l i s h e d P r o(pO, 'S o m e F i e l d') ) ;
                    Write    ( 'I s P u b l i s h e d P r o(pC l a s s,S o m e F i e l)d       :   ') ;
                    W r i t e l n(I s P u b l i s h e d P r o(pO.C l a s s T y p e,' S o m e F i e l d') ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.23          IsStoredProp

    Synopsis:    Check whether a property is stored.

Declaration:     function  IsStoredProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Boolean
                function  IsStoredProp(Instance:  TObject;const  PropName:  String)
                                                     :  Boolean



                                                                                1536

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
    Visibility:  default

Description:     IsStoredProp returns True if the Stored modifier evaluates to True for the property de-
                scribed by PropInfo or with name PropName for object Instance.  It returns False other-
                wise.  If the function returns True, this indicates that the property should be written when
                streaming the object Instance.

                If there was no stored modifier in the declaration of the property, True will be returned.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                property  of  Instance.  Specifying  an  invalid  property  name  in  PropName  will  result  in  an
                EPropertyError exception.

    See also:    IsPublishedProp (1536   ), PropIsType (1537   )


                Listing:  ./typinfex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s S t o r e d P r o pf u n c t i o n }


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' S t o r e d t e s t s       :  ' ) ;
                    Write    ( 'I s S t o r e d P r o(pO , S t o r e d I n t e g e r C o n s t F a l)s e   :   ' ) ;
                    W r i t e l n(I s S t o r e d P r o(pO ,' S t o r e d I n t e g e r C o n s t F a l's)e) ;
                    Write    ( 'I s S t o r e d P r o(pO ,S t o r e d I n t e g e r C o n s t T r)u e      :   ' ) ;
                    W r i t e l n(I s S t o r e d P r o(pO ,' S t o r e d I n t e g e r C o n s t T r'u)e) ;
                    Write    ( 'I s S t o r e d P r o(pO ,S t o r e d I n t e g e r M e t h o)d            :   ' ) ;
                    W r i t e l n(I s S t o r e d P r o(pO ,' S t o r e d I n t e g e r M e t h'o)d) ;
                    Write    ( 'I s S t o r e d P r o(pO , S t o r e d I n t e g e r V i r t u a l M e t)h o:d ' ) ;
                    W r i t e l n(I s S t o r e d P r o(pO ,' S t o r e d I n t e g e r V i r t u a l M e t h'o)d) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.24          PropIsType

    Synopsis:    Check the type of a published property.

Declaration:     function  PropIsType(Instance:  TObject;const  PropName:  String;
                                                TypeKind:  TTypeKind)  :  Boolean
                function  PropIsType(AClass:  TClass;const  PropName:  String;
                                                TypeKind:  TTypeKind)  :  Boolean

    Visibility:   default

Description:     PropIsType returns True if the property with name PropName has type TypeKind.  It returns
                False otherwise.  The class to be examined can be specified in one of two ways:


                AClass     A class pointer.



                                                                                1537

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                Instance     An instance of the class.


       Errors:   No checks are done to ensure Instance or AClass are valid pointers.Specifying an invalid
                property name in PropName will result in an EPropertyError exception.

    See also:    IsPublishedProp (1536   ), IsStoredProp (1536   ), PropType (1538   )


                Listing:  ./typinfex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e P r o p I s T y p e f u n c t i o n}


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' P r o p e r t y t e s t s      :   ' ) ;
                    Write    ( 'P r o p I s T y p e(O, B o o l e a n F i e l,dt k B o o l)         :  ' ) ;
                    W r i t e l n(P r o p I s T y p(eO , 'B o o l e a n F i e l d',t k B o o l) ) ;
                    Write    ( 'P r o p I s T y p e(C l a s s,B o o l e a n F i e l,dt k B o o l)  :  ' ) ;
                    W r i t e l n(P r o p I s T y p(eO . C l a s s T y p,e' B o o l e a n F i e l'd,t k B o o l) ) ;
                    Write    ( 'P r o p I s T y p e(O, B y t e F i e l d,t k S t r i n)g           :  ' ) ;
                    W r i t e l n(P r o p i s T y p(eO , ' B y t e F i e l'd, t k S t r i n g) ) ;
                    Write    ( 'P r o p I s T y p e(C l a s s,B y t e F i e l d,t k S t r i n)g    :  ' ) ;
                    W r i t e l n(P r o p I s T y p(eO . C l a s s T y p,e' B y t e F i e l d',t k S t r i n g) ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.25          PropType

    Synopsis:    Return the type of a property

Declaration:     function  PropType(Instance:  TObject;const  PropName:  String)  :  TTypeKind
                function  PropType(AClass:  TClass;const  PropName:  String)  :  TTypeKind

    Visibility:   default

Description:     Proptype returns the type of the property PropName for a class.  The class to be examined
                can be specified in one of 2 ways:


                AClass     A class pointer.

                Instance     An instance of the class.


       Errors:   No checks are done to ensure Instance or AClass are valid pointers.  Specifying an invalid
                property name in PropName will result in an EPropertyError exception.

    See also:    IsPublishedProp (1536   ), IsStoredProp (1536   ), PropIsType (1537   )


                Listing:  ./typinfex/ex17.pp


                                                                                1538

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e PropType        f u n c t i o n }


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    W r i t e l n(' P r o p e r t y t e s t s      :   ' ) ;
                    Write    ( 'PropType      (O  , B o o l e a n F i e l)d        :   ') ;
                    W r i t e l n(TypeNames       [PropType      ( O , 'B o o l e a n F i e l d') ] ) ;
                    Write    ( 'PropType      ( C l a s s,B o o l e a n F i e l d)  :  ') ;
                    W r i t e l n(TypeNames       [PropType      ( O . C l a s s T y p,e' B o o l e a n F i e l'd) ] ) ;
                    Write    ( 'PropType      (O  , B y t e F i e l)d              :   ') ;
                    W r i t e l n(TypeNames       [PropType      ( O , 'B y t e F i e l d') ] ) ;
                    Write    ( 'PropType      ( C l a s s, B y t e F i e l)d       :   ') ;
                    W r i t e l n(TypeNames       [PropType      ( O . C l a s s T y p,e' B y t e F i e l d') ] ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.26          SetEnumProp

    Synopsis:    Set value of an enumerated-type property

Declaration:     procedure  SetEnumProp(Instance:  TObject;const  PropName:  String;
                                                   const  Value:  String)
                procedure  SetEnumProp(Instance:  TObject;const  PropInfo:  PPropInfo;
                                                   const  Value:  String)

    Visibility:   default

Description:     SetEnumProp sets the property described by  PropInfo or with name PropName to Value.
                Value  must  be  a  string  with  the  name  of  the  enumerate  value,  i.e.  it  can  be  used  as  an
                argument to GetEnumValue (1522   ).

                For an example, see GetEnumProp (1522   ).

       Errors:   No checks are done to ensure Instance or PropInfo are valid pointers.  Specifying an invalid
                property name in PropName will result in an EPropertyError exception.

    See also:    GetEnumProp (1522   ), SetStrProp (1543   ), SetFloatProp (1539   ), SetInt64Prop (1540   ), Set-
                MethodProp (1541   )
                31.7.27          SetFloatProp

    Synopsis:    Set value of a float property.

Declaration:     procedure  SetFloatProp(Instance:  TObject;const  PropName:  String;
                                                     Value:  Extended)
                procedure  SetFloatProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                     Value:  Extended)



                                                                                1539

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
    Visibility:  default

Description:     SetFloatProp assigns Value to the property described by PropInfo or with name Propname
                for the object Instance.

                For an example, see GetFloatProp (1523   ).

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                float property of  Instance.  Specifying an invalid property name in PropName will result in
                an EPropertyError exception.

    See also:    GetFloatProp  (1523   ),  SetOrdProp  (1542   ),  SetStrProp  (1543   ),  SetInt64Prop  (1540   ),  Set-
                MethodProp (1541   )
                31.7.28          SetInt64Prop

    Synopsis:    Set value of a Int64 property

Declaration:     procedure  SetInt64Prop(Instance:  TObject;PropInfo:  PPropInfo;
                                                     const  Value:  Int64)
                procedure  SetInt64Prop(Instance:  TObject;const  PropName:  String;
                                                     const  Value:  Int64)

    Visibility:   default

Description:     SetInt64Prop assigns Value to the property of type Int64 that is described by PropInfo
                or with name Propname for the object Instance.

                For an example, see GetInt64Prop (1524   ).

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                Int64 property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    GetInt64Prop (1524   ), GetMethodProp (1525   ), SetOrdProp (1542   ), SetStrProp (1543   ), Set-
                FloatProp (1539   )
                31.7.29          SetInterfaceProp

    Synopsis:    Set interface-valued property

Declaration:     procedure  SetInterfaceProp(Instance:  TObject;const  PropName:  String;
                                                           const  Value:  IInterface)
                procedure  SetInterfaceProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                           const  Value:  IInterface)

    Visibility:   default

Description:     SetInterfaceProp assigns Value to the the object property described by PropInfo or with
                name Propname for the object Instance.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                interface property of Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    GetInterfaceProp  (1525   ),  SetObjectProp  (1541   ),  SetOrdProp  (1542   ),  SetStrProp  (1543   ),
                SetFloatProp (1539   ), SetInt64Prop (1540   ), SetMethodProp (1541   )


                                                                                1540

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.30          SetMethodProp

    Synopsis:    Set the value of a method property

Declaration:     procedure  SetMethodProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                      const  Value:  TMethod)
                procedure  SetMethodProp(Instance:  TObject;const  PropName:  String;
                                                      const  Value:  TMethod)

    Visibility:   default

Description:     SetMethodProp assigns Value to the method the property described by PropInfo or with
                name Propname for object Instance.

                The type TMethod of the Value parameter is defined in the SysUtils unit as:


                TMethod  =  packed  record
                    Code,  Data:  Pointer;
                end;


                Data should point to the instance of the class with the method Code.

                For an example, see GetMethodProp (1525   ).

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                method property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    GetMethodProp (1525   ), SetOrdProp (1542   ), SetStrProp (1543   ), SetFloatProp (1539   ), SetInt64Prop
                (1540   )
                31.7.31          SetObjectProp

    Synopsis:    Set the value of an object-type property.

Declaration:     procedure  SetObjectProp(Instance:  TObject;const  PropName:  String;
                                                      Value:  TObject)
                procedure  SetObjectProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                      Value:  TObject)

    Visibility:   default

Description:     SetObjectProp  assigns  Value  to  the  the  object  property  described  by  PropInfo  or  with
                name Propname for the object Instance.

                For an example, see GetObjectProp (1527   ).

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                object property of  Instance.  Specifying an invalid property name in PropName will result
                in an EPropertyError exception.

    See also:    GetObjectProp (1527   ), SetOrdProp (1542   ), SetStrProp (1543   ), SetFloatProp (1539   ), SetInt64Prop
                (1540   ), SetMethodProp (1541   )


                                                                                1541

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.32          SetOrdProp

    Synopsis:    Set value of an ordinal property

Declaration:     procedure  SetOrdProp(Instance:  TObject;PropInfo:  PPropInfo;Value:  Int64)
                procedure  SetOrdProp(Instance:  TObject;const  PropName:  String;
                                                 Value:  Int64)

    Visibility:   default

Description:     SetOrdProp assigns Value to the the ordinal property described by PropInfo or with name
                Propname for the object Instance.

                Ordinal properties that can be set include:


                Integers and subranges of integers                    The actual value of the integer must be passed.

                Enumerated types and subranges of enumerated types                                    The ordinal value of the enu-
                       merated type must be passed.

                Subrange types           of integers or enumerated types.  Here the ordinal value must be passed.

                Sets   If the base type of the set has less than 31 possible values.  For each possible value; the
                       corresponding bit of  Value must be set.


                For an example, see GetOrdProp (1529   ).

       Errors:   No checking is done whether Instance is non-nil, or whether PropInfo describes a valid or-
                dinal property of Instance.  No range checking is performed.  Specifying an invalid property
                name in PropName will result in an EPropertyError exception.

    See also:    GetOrdProp  (1529   ),  SetStrProp  (1543   ),  SetFloatProp  (1539   ),  SetInt64Prop  (1540   ),  Set-
                MethodProp (1541   )
                31.7.33          SetPropValue

    Synopsis:    Set property value as variant

Declaration:     procedure  SetPropValue(Instance:  TObject;const  PropName:  String;
                                                     const  Value:  Variant)

    Visibility:   default

Description:     Due  to  missing  Variant  support,  this  function  is  not  yet  implemented;  it  is  provided  for
                Delphi compatibility only.

       Errors:
                31.7.34          SetSetProp

    Synopsis:    Set value of set-typed property.

Declaration:     procedure  SetSetProp(Instance:  TObject;const  PropName:  String;
                                                 const  Value:  String)
                procedure  SetSetProp(Instance:  TObject;const  PropInfo:  PPropInfo;
                                                 const  Value:  String)

    Visibility:   default



                                                                                1542

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
Description:     SetSetProp sets the property specified by  PropInfo or PropName for object Instance to
                Value.  Value is a string which contains a comma-separated list of values, each value being a
                string-representation of the enumerated value that should be included in the set.  The value
                should be accepted by the StringToSet (1545   ) function.

                The value can be formed using the SetToString (1543   ) function.

                For an example, see GetSetProp (1532   ).

       Errors:   No checking is done whether Instance is non-nil, or whether PropInfo describes a valid or-
                dinal property of Instance.  No range checking is performed.  Specifying an invalid property
                name in PropName will result in an EPropertyError exception.

    See also:    GetSetProp (1532   ), SetOrdProp (1542   ), SetStrProp (1543   ), SetFloatProp (1539   ), SetInt64Prop
                (1540   ), SetMethodProp (1541   ), SetToString (1543   ), StringToSet (1545   )
                31.7.35          SetStrProp

    Synopsis:    Set value of a string property

Declaration:     procedure  SetStrProp(Instance:  TObject;const  PropName:  String;
                                                 const  Value:  AnsiString)
                procedure  SetStrProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                 const  Value:  Ansistring)

    Visibility:   default

Description:     SetStrProp  assigns  Value  to  the  string  property  described  by  PropInfo  or  with  name
                Propname for object Instance.

                For an example, see GetStrProp (1534   )

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                string property of Instance.  Specifying an invalid property name in PropName will result in
                an EPropertyError exception.

    See also:    GetStrProp (1534   ), SetWideStrProp (1545   ), SetOrdProp (1542   ), SetFloatProp (1539   ), SetInt64Prop
                (1540   ), SetMethodProp (1541   )
                31.7.36          SetToString

    Synopsis:    Convert set to a string description

Declaration:     function  SetToString(TypeInfo:  PTypeInfo;Value:  Integer;
                                                 Brackets:  Boolean)  :  String
                function  SetToString(PropInfo:  PPropInfo;Value:  Integer;
                                                 Brackets:  Boolean)  :  String
                function  SetToString(PropInfo:  PPropInfo;Value:  Integer)  :  String

    Visibility:   default

Description:     SetToString takes an integer representation of a set (as received e.g.  by GetOrdProp) and
                turns  it  into  a  string  representing  the  elements  in  the  set,  based  on  the  type  information
                found  in  the  PropInfo  property  information.  By  default,  the  string  representation  is  not
                surrounded by square brackets.  Setting the Brackets parameter to True will surround the
                string representation with brackets.

                The function returns the string representation of the set.

                                                                                1543

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
       Errors:   No checking is done to see whether PropInfo points to valid property information.

    See also:    GetEnumName (1520   ), GetEnumValue (1522   ), StringToSet (1545   )


                Listing:  ./typinfex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 1 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S e t T o S t r i n gf u n c t i o n }


                { $mode      o b j f p c}


                 u s e s r t t i o b j,t y p i n f o;


                Var
                    O   :  TMyTestObject          ;
                    PI   :   P P r o p I n f o;
                    I   :  l o n g i n t;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  G e t P r o p I n f(oO , 'S e t F i e l d') ;
                    O . S e t F i e l:d= [ m e f i r s t,meSecond      ,meThird      ] ;
                    I := GetOrdProp        (O , PI  ) ;
                    W r i t e l n(' S e t  p r o p e r t yt o   s t r i n g :   ') ;
                    W r i t e l n(' V a l u e   :   ', S e t T o S t r i n(gPI , I , F a l s e) ) ;
                    O . S e t F i e l:d= [ m e f i r s t,meSecond      ] ;
                    I := GetOrdProp        (O , PI  ) ;
                    W r i t e l n(' V a l u e   :   ', S e t T o S t r i n(gPI , I ,True    ) ) ;
                    I := S t r i n g T o S e(tPI  , 'm e f i r s t') ;
                    S e t O r d P r o(pO , PI , I ) ;
                    I := GetOrdProp        (O , PI  ) ;
                    W r i t e l n(' V a l u e   :   ', S e t T o S t r i n(gPI , I , F a l s e) ) ;
                    I := S t r i n g T o S e(tPI  , '[ mesecond      , m e t h i r d]') ;
                    S e t O r d P r o(pO , PI , I ) ;
                    I := GetOrdProp        (O , PI  ) ;
                    W r i t e l n(' V a l u e   :   ', S e t T o S t r i n(gPI , I ,True    ) ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________

                31.7.37          SetVariantProp

    Synopsis:    Set value of a variant property

Declaration:     procedure  SetVariantProp(Instance:  TObject;const  PropName:  String;
                                                        const  Value:  Variant)
                procedure  SetVariantProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                        const  Value:  Variant)

    Visibility:   default

Description:     Due to missing Variant support, this function is not yet implemented.  Provided for Delphi
                compatibility only.

       Errors:



                                                                                1544

                ________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________
                31.7.38          SetWideStrProp

    Synopsis:    Set a widestring property

Declaration:     procedure  SetWideStrProp(Instance:  TObject;const  PropName:  String;
                                                        const  Value:  WideString)
                procedure  SetWideStrProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                        const  Value:  WideString)

    Visibility:   default

Description:     SetWideStrProp assigns Value to the widestring property described by PropInfo or with
                name Propname for object Instance.

       Errors:   No  checking  is  done  whether  Instance  is  non-nil,  or  whether  PropInfo  describes  a  valid
                widestring  property  of  Instance.   Specifying  an  invalid  property  name  in  PropName  will
                result in an EPropertyError exception.

    See also:    GetWideStrProp (1535   ), SetStrProp (1543   ), SetOrdProp (1542   ), SetFloatProp (1539   ), SetInt64Prop
                (1540   ), SetMethodProp (1541   )
                31.7.39          StringToSet

    Synopsis:    Convert string description to a set.

Declaration:     function  StringToSet(PropInfo:  PPropInfo;const  Value:  String)  :  Integer
                function  StringToSet(TypeInfo:  PTypeInfo;const  Value:  String)  :  Integer

    Visibility:   default

Description:     StringToSet converts the string representation of a set in Value to a integer representation
                of  the  set,  using  the  property  information  found  in  PropInfo.  This  property  information
                should point to the property information of a set property.  The function returns the integer
                representation of the set.  (i.e, the set value, typecast to an integer)

                The string representation can be surrounded with square brackets, and must consist of the
                names of the elements of the base type of the set.  The base type of the set should be an
                enumerated type.  The elements should be separated by commas, and may be surrounded by
                spaces.  each of the names will be fed to the GetEnumValue (1522   ) function.

                For an example, see SetToString (1543   ).

       Errors:   No  checking  is  done  to  see  whether  PropInfo  points  to  valid  property  information.  If  a
                wrong name is given for an enumerated value, then an EPropertyError will be raised.

    See also:    GetEnumName (1520   ), GetEnumValue (1522   ), SetToString (1543   )
                31.8          EPropertyConvertError



                31.8.1         Description

                EPropertyConvertError is not used in the Free Pascal implementation of the typinfo unit,
                but is declared for Delphi compatibility.



                                                                                1545

________________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___
31.9          EPropertyError



31.9.1         Description

Exception raised in case of an error in one of the functions.

                                                                1546


Chapter   32


Reference   for   unit   'Unix'
32.1          Used  units
                                     Table 32.1:  Used units by unit 'Unix'


                                                  _Name_____________Page______
                                                    BaseUnix            94
                                                    unixtype         1585



32.2          Constants,  types  and  variables



32.2.1         Constants

ARG_MAX  =  UnixType.ARG_MAX


Maximum number of arguments to a program.


fs_ext  =  $137d


File system type (StatFS (1581   )):  (ext) Extended


fs_ext2  =  $ef53


File system type (StatFS (1581   )):  (ext2) Second extended


fs_iso  =  $9660


File system type (StatFS (1581   )):  ISO 9660


fs_minix  =  $137f


File system type (StatFS (1581   )):  Minix


fs_minix_30  =  $138f



                                                            1547

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
File system type (StatFS (1581   )):  Minix 3.0


fs_minux_V2  =  $2468


File system type (StatFS (1581   )):  Minix V2


fs_msdos  =  $4d44


File system type (StatFS (1581   )):  MSDOS (FAT)


fs_nfs  =  $6969


File system type (StatFS (1581   )):  NFS


fs_old_ext2  =  $ef51


File system type (StatFS (1581   )):  (ext2) Old second extended


fs_proc  =  $9fa0


File system type (StatFS (1581   )):  PROC fs


fs_xia  =  $012FD16D


File system type (StatFS (1581   )):  XIA


IOCtl_TCGETS  =  $5401


IOCTL call number:  get Terminal Control settings


LOCK_EX  =  2


FpFLock (1571   ) Exclusive lock


LOCK_NB  =  4


FpFLock (1571   ) Non-blocking operation


LOCK_SH  =  1


FpFLock (1571   ) Shared lock


LOCK_UN  =  8


FpFLock (1571   ) unlock


MAP_FAILED  =  baseunix.MAP_FAILED


Error return value for mmap:  mmap operation failed.


MAP_FIXED  =  baseunix.MAP_FIXED



                                                                1548

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
FpMMap (1547   ) map type:  Interpret addr exactly


MAP_PRIVATE  =  baseunix.MAP_PRIVATE


FpMMap (1547   ) map type:  Changes are private


MAP_SHARED  =  baseunix.MAP_SHARED


FpMMap (1547   ) map type:  Share changes


MAP_TYPE  =  baseunix.MAP_TYPE


FpMMap (1547   ) map type:  Bitmask for type of mapping


MS_ASYNC  =  1


Asynchronous operation flag for msync call


MS_INVALIDATE  =  2


Invalidate other mappings of file flag for msync call


MS_SYNC  =  4


Synchronous operation flag for msync call


NAME_MAX  =  UnixType.NAME_MAX


Maximum filename length.


Open_Accmode  =  3


Bitmask to determine access mode in open flags.


Open_Append  =  2  shl  9


File open mode:  Append to file


Open_Creat  =  1  shl  6


File open mode:  Create if file does not yet exist.


Open_Direct  =  4  shl  12


File open mode:  Minimize caching effects


Open_Directory  =  2  shl  15


File open mode:  File must be directory.


Open_Excl  =  2  shl  6



                                                                1549

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
File open mode:  Open exclusively


Open_LargeFile  =  1  shl  15


File open mode:  Open for 64-bit I/O


Open_NDelay  =  Open_NonBlock


File open mode:  Alias for Open_NonBlock (1550   )


Open_NoCtty  =  4  shl  6


File open mode:  No TTY control.


Open_NoFollow  =  4  shl  15


File open mode:  Fail if file is symbolic link.


Open_NonBlock  =  4  shl  9


File open mode:  Open in non-blocking mode


Open_RdOnly  =  0


File open mode:  Read only


Open_RdWr  =  2


File open mode:  Read/Write


Open_Sync  =  1  shl  12


File open mode:  Write to disc at once


Open_Trunc  =  1  shl  9


File open mode:  Truncate file to length 0


Open_WrOnly  =  1


File open mode:  Write only


PATH_MAX  =  UnixType.PATH_MAX


Maximum pathname length.


PRIO_PGRP  =  UnixType.PRIO_PGRP


fpGetPriority (1547   ) option:  Get process group priority.


PRIO_PROCESS  =  UnixType.PRIO_PROCESS



                                                                1550

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
fpGetPriority (1547   ) option:  Get process priority.


PRIO_USER  =  UnixType.PRIO_USER


fpGetPriority (1547   ) option:  Get user priority.


PROT_EXEC  =  baseunix.PROT_EXEC


FpMMap (1547   ) memory access:  page can be executed


PROT_NONE  =  baseunix.PROT_NONE


FpMMap (1547   ) memory access:  page can not be accessed


PROT_READ  =  baseunix.PROT_READ


FpMMap (1547   ) memory access:  page can be read


PROT_WRITE  =  baseunix.PROT_WRITE


FpMMap (1547   ) memory access:  page can be written


P_IN  =  1


Input file descriptor of pipe pair.


P_OUT  =  2


Output file descriptor of pipe pair.


SIG_MAXSIG  =  UnixType.SIG_MAXSIG


Maximum system signal number.


STAT_IFBLK  =  $6000


File (#rtl.baseunix.stat (126  ) record) mode:  Block device


STAT_IFCHR  =  $2000


File (#rtl.baseunix.stat (126  ) record) mode:  Character device


STAT_IFDIR  =  $4000


File (#rtl.baseunix.stat (126  ) record) mode:  Directory


STAT_IFIFO  =  $1000


File (#rtl.baseunix.stat (126  ) record) mode:  FIFO


STAT_IFLNK  =  $a000



                                                                1551

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
File (#rtl.baseunix.stat (126  ) record) mode:  Link


STAT_IFMT  =  $f000


File (#rtl.baseunix.stat (126  ) record) mode:  File type bit mask


STAT_IFREG  =  $8000


File (#rtl.baseunix.stat (126  ) record) mode:  Regular file


STAT_IFSOCK  =  $c000


File (#rtl.baseunix.stat (126  ) record) mode:  Socket


STAT_IRGRP  =  STAT_IROTH  shl  3


File (#rtl.baseunix.stat (126  ) record) mode:  Group read permission


STAT_IROTH  =  $4


File (#rtl.baseunix.stat (126  ) record) mode:  Other read permission


STAT_IRUSR  =  STAT_IROTH  shl  6


File (#rtl.baseunix.stat (126  ) record) mode:  Owner read permission


STAT_IRWXG  =  STAT_IRWXO  shl  3


File (#rtl.baseunix.stat (126  ) record) mode:  Group permission bits mask


STAT_IRWXO  =  $7


File (#rtl.baseunix.stat (126  ) record) mode:  Other permission bits mask


STAT_IRWXU  =  STAT_IRWXO  shl  6


File (#rtl.baseunix.stat (126  ) record) mode:  Owner permission bits mask


STAT_ISGID  =  $0400


File (#rtl.baseunix.stat (126  ) record) mode:  GID bit set


STAT_ISUID  =  $0800


File (#rtl.baseunix.stat (126  ) record) mode:  UID bit set


STAT_ISVTX  =  $0200


File (#rtl.baseunix.stat (126  ) record) mode:  Sticky bit set


STAT_IWGRP  =  STAT_IWOTH  shl  3



                                                                1552

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
File (#rtl.baseunix.stat (126  ) record) mode:  Group write permission


STAT_IWOTH  =  $2


File (#rtl.baseunix.stat (126  ) record) mode:  Other write permission


STAT_IWUSR  =  STAT_IWOTH  shl  6


File (#rtl.baseunix.stat (126  ) record) mode:  Owner write permission


STAT_IXGRP  =  STAT_IXOTH  shl  3


File (#rtl.baseunix.stat (126  ) record) mode:  Others execute permission


STAT_IXOTH  =  $1


File (#rtl.baseunix.stat (126  ) record) mode:  Others execute permission


STAT_IXUSR  =  STAT_IXOTH  shl  6


File (#rtl.baseunix.stat (126  ) record) mode:  Others execute permission


SYS_NMLN  =  UnixType.SYS_NMLN


Max system name length.


Wait_Any  =  -1


#rtl.baseunix.fpWaitPID (181  ):  Wait on any process


Wait_Clone  =  $80000000


#rtl.baseunix.fpWaitPID (181  ):  Wait on clone processes only.


Wait_MyPGRP  =  0


#rtl.baseunix.fpWaitPID (181  ):  Wait processes from current process group


Wait_NoHang  =  1


#rtl.baseunix.fpWaitPID (181  ):  Do not wait


Wait_UnTraced  =  2


#rtl.baseunix.fpWaitPID (181  ):  Also report stopped but untraced processes
                                                                1553

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
32.2.2         Types

cbool  =  UnixType.cbool


Boolean type


cchar  =  UnixType.cchar


Alias for #rtl.UnixType.cchar (1587   )


cdouble  =  UnixType.cdouble


Double precision real format.


cfloat  =  UnixType.cfloat


Floating-point real format


cint  =  UnixType.cint


C type:  integer (natural size)


cint16  =  UnixType.cint16


C type:  16 bits sized, signed integer.


cint32  =  UnixType.cint32


C type:  32 bits sized, signed integer.


cint64  =  UnixType.cint64


C type:  64 bits sized, signed integer.


cint8  =  UnixType.cint8


C type:  8 bits sized, signed integer.


clock_t  =  UnixType.clock_t


Clock ticks type


clong  =  UnixType.clong


C type:  long signed integer (double sized)


clongdouble  =  UnixType.clongdouble


Usually translates to an extended, but is CPU dependent.


clonglong  =  UnixType.clonglong



                                                                1554

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
C type:  64-bit (double long) signed integer.


cschar  =  UnixType.cschar


Signed character type


cshort  =  UnixType.cshort


C type:  short signed integer (half sized)


csigned  =  UnixType.csigned


csigned is an alias for cint (1554   ).


csint  =  UnixType.csint


Signed integer


cslong  =  UnixType.cslong


The size is CPU dependent.


cslonglong  =  UnixType.cslonglong


cslonglong is an alias for clonglong (1555   ).


csshort  =  UnixType.csshort


Short signed integer type


cuchar  =  UnixType.cuchar


Alias for #rtl.UnixType.cuchar (1588   )


cuint  =  UnixType.cuint


C type:  unsigned integer (natural size)


cuint16  =  UnixType.cuint16


C type:  16 bits sized, unsigned integer.


cuint32  =  UnixType.cuint32


C type:  32 bits sized, unsigned integer.


cuint64  =  UnixType.cuint64


C type:  64 bits sized, unsigned integer.


cuint8  =  UnixType.cuint8



                                                                1555

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
C type:  8 bits sized, unsigned integer.


culong  =  UnixType.culong


C type:  long unsigned integer (double sized)


culonglong  =  UnixType.culonglong


C type:  64-bit (double long) unsigned integer.


cunsigned  =  UnixType.cunsigned


Alias for #rtl.unixtype.cunsigned (1589   )


cushort  =  UnixType.cushort


C type:  short unsigned integer (half sized)


dev_t  =  UnixType.dev_t


Device descriptor type.


gid_t  =  UnixType.gid_t


Group ID type.


ino_t  =  UnixType.ino_t


Inode type.


mode_t  =  UnixType.mode_t


Inode mode type.


nlink_t  =  UnixType.nlink_t


Number of links type.


off_t  =  UnixType.off_t


Offset type.


pcbool  =  UnixType.pcbool


Pointer to boolean type cbool (1554   )


pcchar  =  UnixType.pcchar


Alias for #rtl.UnixType.pcchar (1590   )


pcdouble  =  UnixType.pcdouble



                                                                1556

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
Pointer to cdouble (116  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (116  ) type.


pcint  =  UnixType.pcint


Pointer to cInt (1554   ) type.


pcint16  =  UnixType.pcint16


Pointer to 16-bit signed integer type


pcint32  =  UnixType.pcint32


Pointer to signed 32-bit integer type


pcint64  =  UnixType.pcint64


Pointer to signed 64-bit integer type


pcint8  =  UnixType.pcint8


Pointer to 8-bits signed integer type


pClock  =  UnixType.pClock


Pointer to TClock (1560   ) type.


pclong  =  UnixType.pclong


Pointer to cLong (1554   ) type.


pclongdouble  =  UnixType.pclongdouble


Pointer to the long double type clongdouble (1554   )


pclonglong  =  UnixType.pclonglong


Pointer to longlong type.


pcschar  =  UnixType.pcschar


Pointer to character type cschar (1555   ).


pcshort  =  UnixType.pcshort


Pointer to cShort (1555   ) type.


pcsigned  =  UnixType.pcsigned



                                                                1557

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
Pointer to signed integer type csigned (1555   ).


pcsint  =  UnixType.pcsint


Pointer to signed integer type csint (1555   )


pcslong  =  UnixType.pcslong


Pointer ot the signed long cslong (1555   )


pcslonglong  =  UnixType.pcslonglong


Pointer to Signed longlong type cslonglong (1555   )


pcsshort  =  UnixType.pcsshort


Pointer to short signed integer type csshort (1555   )


pcuchar  =  UnixType.pcuchar


Alias for #rtl.UnixType.pcuchar (1591   )


pcuint  =  UnixType.pcuint


Pointer to cUInt (1555   ) type.


pcuint16  =  UnixType.pcuint16


Pointer to 16-bit unsigned integer type


pcuint32  =  UnixType.pcuint32


Pointer to unsigned 32-bit integer type


pcuint64  =  UnixType.pcuint64


Pointer to unsigned 64-bit integer type


pcuint8  =  UnixType.pcuint8


Pointer to 8-bits unsigned integer type


pculong  =  UnixType.pculong


Pointer to cuLong (1556   ) type.


pculonglong  =  UnixType.pculonglong


Unsigned longlong type


pcunsigned  =  UnixType.pcunsigned



                                                                1558

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
Alias for #rtl.unixtype.pcunsigned (1592   )


pcushort  =  UnixType.pcushort


Pointer to cuShort (1556   ) type.


pDev  =  UnixType.pDev


Pointer to TDev (1560   ) type.


pGid  =  UnixType.pGid


Pointer to TGid (1561   ) type.


pid_t  =  UnixType.pid_t


Process ID type.


pIno  =  UnixType.pIno


Pointer to TIno (1561   ) type.


pMode  =  UnixType.pMode


Pointer to TMode (1561   ) type.


pnLink  =  UnixType.pnLink


Pointer to TnLink (1561   ) type.


pOff  =  UnixType.pOff


Pointer to TOff (1561   ) type.


pPid  =  UnixType.pPid


Pointer to TPid (1562   ) type.


pSize  =  UnixType.pSize


Pointer to TSize (1562   ) type.


pSocklen  =  UnixType.pSocklen


Pointer to TSockLen (1562   ) type.


psSize  =  UnixType.psSize


Pointer to TsSize (1562   ) type


pthread_cond_t  =  UnixType.pthread_cond_t



                                                                1559

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
Thread conditional variable type.


pthread_mutex_t  =  UnixType.pthread_mutex_t


Thread mutex type.


pthread_t  =  UnixType.pthread_t


Posix thread type.


pTime  =  UnixType.pTime


Pointer to TTime (1562   ) type.


ptimespec  =  UnixType.ptimespec


Pointer to timespec (1561   ) type.


ptimeval  =  UnixType.ptimeval


Pointer to timeval (1561   ) type.


ptime_t  =  UnixType.ptime_t


Pointer to time_t (1561   ) type.


pUid  =  UnixType.pUid


Pointer to TUid (1562   ) type.


size_t  =  UnixType.size_t


Size specification type.


socklen_t  =  UnixType.socklen_t


Socket address length type.


ssize_t  =  UnixType.ssize_t


Small size type.


TClock  =  UnixType.TClock


Alias for clock_t (1554   ) type.


TDev  =  UnixType.TDev


Alias for dev_t (1556   ) type.
                                                                1560

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___

                       Table 32.2:  Enumeration values for type TFSearchOption



__Value_____________________________Explanation____________________________________________________________________________________*
 *___________
  CurrentDirectoryFirst             Search the current directory first, before all directories in the search path.
  CurrentDirectoryLast              Search the current directory last, after all directories in the search path
  NoCurrentDirectory                Do not search the current directory unless it is specified in the search path.

TFSearchOption  =  (NoCurrentDirectory,CurrentDirectoryFirst,
                             CurrentDirectoryLast)


Describes the search strategy used by FSearch (1573   )


TGid  =  UnixType.TGid


Alias for gid_t (1556   ) type.


timespec  =  UnixType.timespec


Short time specification type.


timeval  =  UnixType.timeval


Time specification type.


time_t  =  UnixType.time_t


Time span type


TIno  =  UnixType.TIno


Alias for ino_t (1556   ) type.


TIOCtlRequest  =  UnixType.TIOCtlRequest


Alias for the TIOCtlRequest (1597   ) type in unixtypes


TMode  =  UnixType.TMode


Alias for mode_t (1556   ) type.


TnLink  =  UnixType.TnLink


Alias for nlink_t (1556   ) type.


TOff  =  UnixType.TOff


Alias for off_t (1556   ) type.
                                                                1561

______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___
TPid  =  UnixType.TPid


Alias for pid_t (1559   ) type.


Tpipe  =  baseunix.tfildes


Array describing a pipe pair of filedescriptors.


TSize  =  UnixType.TSize


Alias for size_t (1560   ) type


TSocklen  =  UnixType.TSocklen


Alias for socklen_t (1560   ) type.


TsSize  =  UnixType.TsSize


Alias for ssize_t (1560   ) type


tstatfs  =  UnixType.TStatFs


Record describing a file system in the baseunix.fpstatfs (1547   ) call.


TTime  =  UnixType.TTime


Alias for TTime (1562   ) type.


Ttimespec  =  UnixType.Ttimespec


Alias for TimeSpec (1561   ) type.


TTimeVal  =  UnixType.TTimeVal


Alias for timeval (1561   ) type.


TUid  =  UnixType.TUid


Alias for uid_t (1562   ) type.


uid_t  =  UnixType.uid_t


User ID type
32.2.3         Variables

tzdaylight  :  Boolean


Indicates whether daylight savings time is active.


tzname  :  Array[boolean]  of  pchar


Timezone name.



                                                                1562

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3          Procedures  and  functions



                32.3.1         AssignPipe

    Synopsis:    Create a set of pipe file handlers

Declaration:     function  AssignPipe(var  pipe_in:  cint;var  pipe_out:  cint)  :  cint
                function  AssignPipe(var  pipe_in:  text;var  pipe_out:  text)  :  cint
                function  AssignPipe(var  pipe_in:  File;var  pipe_out:  File)  :  cint

    Visibility:   default

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, extended error information is returned by the
                FpGetErrno (145  ) function:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    POpen (1578   ), #rtl.baseunix.FpMkFifo (153  )


                Listing:  ./unixex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n P i p ef u n c t i o n.  }


                Uses     B a s e U n i x,U n i x;


                Var     p i p i,p i p o  :  T e x t ;
                        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 gP i p e s. ') ;
                    I f  a s s i g n p i p e(p i p i,p i p o)<>0     then
                        W r i t e l n('E r r o r  a s s i g n i n gp i p e s  ! ', f p g e t e r r n)o;
                    W r i t e l n ( ' W r i t i n gt o   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 f r o m  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     f r o m 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___.____________________________________________________________________________________________________________*
 *___________


                                                                                1563

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.2         AssignStream

    Synopsis:    Assign stream for in and output to a program

Declaration:     function  AssignStream(var  StreamIn:  text;var  Streamout:  text;
                                                   const  Prog:  ansiString;
                                                   const  args:  Array  of  ansistring)  :  cint
                function  AssignStream(var  StreamIn:  text;var  Streamout:  text;
                                                   var  streamerr:  text;const  Prog:  ansiString;
                                                   const  args:  Array  of  ansistring)  :  cint

    Visibility:   default

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
                input and output (and standard error) of  Prog.  Prog is the path of a program (including
                path).  The options for the program can be specified in Args.

                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:   Extended error information is returned by the FpGetErrno (145  ) function.


                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 (1563   ), POpen (1578   )


                Listing:  ./unixex/ex38.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   Program       t o  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     B a s e U n i x,U n i x;


                Var     S i, So   :  T e x t ;
                       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)=  '- s o n ' )  then
                        b e g i n
                        W r i t e l n(  'C a l l i n g s o n' ) ;
                        A s s i g n s t r e a m(S i ,So  , '. / e x 3 8' , ['- s o n ' ] ) ;
                        i f  f p g e t e r r n<o>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 mf a i l e d ! ' ) ;
                           h a l t( 1 ) ;
                           end  ;



                                                                                1564

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                        W r i t e l n(  'S p e a k i n g t o  s o n' ) ;
                       For     i: = 1  t o  1 0  do
                           b e g i n
                           w r i t e l n ( so , ' H e l l o s o n  ! ' ) ;
                           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 t o  s o n . . .' ) ;
                           end  ;
                       For     i: = 1  t o  3   do   w r i t e l n ( so , ' H e l l o c h a p  ! ' ) ;
                        c l o s e ( s o) ;
                        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) ;
                        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  s o n  ' ) ;
                       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 s o n  ! ' ,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___.____________________________________________________________________________________________________________*
 *___________

                32.3.3         FpExecL

    Synopsis:    Execute process (using argument list, environment)

Declaration:     function  FpExecL(const  PathName:  AnsiString;
                                           const  S:  Array  of  AnsiString)  :  cint

    Visibility:   default

Description:     FpExecL replaces the currently running program with the program, specified in PathName.  S
                is an array of command options.  The executable in PathName must be an absolute pathname.
                The current process' environment is passed to the program.  On success, FpExecL does not
                return.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                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.



                                                                                1565

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                sys__enotdir     A component of the path is not a directory.

                sys__eloop    The path contains a circular reference (via symlinks).


    See also:    #rtl.baseunix.fpexecve (139  ), FpExecv (1568   ), FpExecvp (1569   ), FpExecle (1566   ), FpExe-
                clp (1567   ), #rtl.baseunix.FpFork (142  )


                Listing:  ./unixex/ex77.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 7;


                {   Program       t o  d e m o n s t r a t et h e  FPExecL       f u n c t i o n. }


                Uses     Unix    ,  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.}
                    FpExecL       ( '/ b i n/ l s ' , ['-  l' ] ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.4         FpExecLE

    Synopsis:    Execute process (using argument list, environment)

Declaration:     function  FpExecLE(const  PathName:  AnsiString;
                                            const  S:  Array  of  AnsiString;MyEnv:  ppchar)  :  cint

    Visibility:   default

Description:     FpExecLE replaces the currently running program with the program, specified in PathName.
                S is an array of command options.  The executable in PathName must be an absolute path-
                name.  The environment in MyEnv is passed to the program.  On success, FpExecLE does not
                return.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                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:    #rtl.baseunix.fpexecve (139  ), FpExecv (1568   ), FpExecvp (1569   ), FpExecl (1565   ), FpExeclp
                (1567   ), #rtl.baseunix.FpFork (142  )


                Listing:  ./unixex/ex11.pp
                                                                                1566

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   Program       t o  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     Unix    ,  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 n v p  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' , e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.5         FpExecLP

    Synopsis:    Execute process (using argument list, environment; search path)

Declaration:     function  FpExecLP(const  PathName:  AnsiString;
                                            const  S:  Array  of  AnsiString)  :  cint

    Visibility:   default

Description:     FpExecLP replaces the currently running program with the program, specified in PathName.
                S is an array of command options.  The executable in PathName is searched in the path, if it
                isn't an absolute filename.  The current environment is passed to the program.  On success,
                FpExecLP does not return.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                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:    #rtl.baseunix.fpexecve (139  ), FpExecv (1568   ), FpExecvp (1569   ), FpExecle (1566   ), FpExecl
                (1565   ), #rtl.baseunix.FpFork (142  )


                Listing:  ./unixex/ex76.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 6;


                {   Program       t o  d e m o n s t r a t et h e  F p E x e c l p f u n c t i o n. }


                Uses     Unix    ,  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.}



                                                                                1567

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                    {  e n v p  i s   d e f i n e d i n  t h e  s y s t e m u n i t.}
                    F p E x e c l p ( 'l s ' , ['-  l' ] ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.6         FpExecLPE

    Synopsis:    Execute a program in the path, and pass it an environment

Declaration:     function  FpExecLPE(const  PathName:  AnsiString;
                                              const  S:  Array  of  AnsiString;env:  ppchar)  :  cint

    Visibility:   default

Description:     FpExecLPE does the same as FpExecLP (1567   ), but additionally it specifies the environment
                for the new process in env, a pointer to a null-terminated array of null-terminated strings.

       Errors:   On success, this function does not return.

    See also:    FpExecLP (1567   ), FpExecLE (1566   )
                32.3.7         FpExecV

    Synopsis:    Execute process

Declaration:     function  FpExecV(const  PathName:  AnsiString;args:  ppchar)  :  cint

    Visibility:   default

Description:     FpExecV replaces the currently running program with the program, specified in PathName.
                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, FpExecV does not return.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                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:    #rtl.baseunix.fpexecve (139  ), FpExecvp (1569   ), FpExecle (1566   ), FpExecl (1565   ), FpExeclp
                (1567   ), #rtl.baseunix.FpFork (142  )


                Listing:  ./unixex/ex8.pp


                                                                                1568

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v  f u n c t i o n. }


                Uses     Unix    ,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    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}
                    f p E x e c v ( '/ b i n/ l s ' ,pp  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.8         FpExecVP

    Synopsis:    Execute process, search path

Declaration:     function  FpExecVP(const  PathName:  AnsiString;args:  ppchar)  :  cint

    Visibility:   default

Description:     FpExecVP replaces the currently running program with the program, specified in PathName.
                The executable 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:   Extended error information is returned by the FpGetErrno (145  ) function:


                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:    #rtl.baseunix.fpexecve (139  ), FpExecv (1568   ), FpExecle (1566   ), FpExecl (1565   ), FpExeclp
                (1567   ), #rtl.baseunix.FpFork (142  )


                Listing:  ./unixex/ex79.pp


                                                                                1569

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 9;


                {   Program       t o  d e m o n s t r a t et h e  FpExecVP        f u n c t i o n. }


                Uses     Unix    ,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' l s ';
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 2 ] : =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.}
                    f p E x e c v p ( 'l s ' ,pp  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.9         FpExecVPE

    Synopsis:    Execute process, search path using environment

Declaration:     function  FpExecVPE(const  PathName:  AnsiString;args:  ppchar;env:  ppchar)
                                                :  cint

    Visibility:   default

Description:     FpExecVP replaces the currently running program with the program, specified in PathName.
                The executable 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 environment in Env is passed to
                the program.  On success, execvp does not return.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                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:    #rtl.baseunix.fpexecve (139  ), FpExecv (1568   ), FpExecle (1566   ), FpExecl (1565   ), FpExeclp
                (1567   ), #rtl.baseunix.FpFork (142  )


                Listing:  ./unixex/ex79.pp



                                                                                1570

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 9;


                {   Program       t o  d e m o n s t r a t et h e  FpExecVP        f u n c t i o n. }


                Uses     Unix    ,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' l s ';
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 2 ] : =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.}
                    f p E x e c v p ( 'l s ' ,pp  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.10          fpFlock

    Synopsis:    Lock a file (advisory lock)

Declaration:     function  fpFlock(var  T:  text;mode:  cint)  :  cint
                function  fpFlock(var  F:  File;mode:  cint)  :  cint
                function  fpFlock(fd:  cint;mode:  cint)  :  cint

    Visibility:   default

Description:     FpFLock 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 zero if successful, a nonzero return value indicates an error.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:

    See also:    #rtl.baseunix.FpFcntl (141  ), FSync (1575   )
                32.3.11          fpfStatFS

    Synopsis:    Retrieve filesystem information.

Declaration:     function  fpfStatFS(Fd:  cint;Info:  PStatFS)  :  cint

    Visibility:   default



                                                                                1571

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
Description:     fpStatFS returns in Info information about the filesystem on which the open file descriptor
                fd resides.  Info is of type tstatfs.  The function returns 0 if the call was succesfull, or an
                error code if the call failed.

       Errors:   On error, a non-zero error code is returned

    See also:    fpStatFS (1572   ), fpfStat (1547   )
                32.3.12          fpfsync

    Synopsis:    Flush cached data to disk

Declaration:     function  fpfsync(fd:  cint)  :  cint

    Visibility:   default

Description:     fpfsync forces the system to write all paged (in-memory) changes to file descriptor fd to
                disk.  If the call was succesful, 0 is returned.

       Errors:   On error, a nonzero error-code is returned.
                32.3.13          fpgettimeofday

    Synopsis:    Return kernel time of day in GMT

Declaration:     function  fpgettimeofday(tp:  ptimeval;tzp:  ptimezone)  :  cint

    Visibility:   default

Description:     FpGetTimeOfDay  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.

       Errors:   None.
                32.3.14          fpStatFS

    Synopsis:    Retrieve filesystem information.

Declaration:     function  fpStatFS(Path:  pchar;Info:  PStatFS)  :  cint

    Visibility:   default

Description:     fpStatFS returns in Info information about the filesystem on which the file or path Path
                resides.  Info is of type tstatfs.  The function returns 0 if the call was succesfull, or an error
                code if the call failed.

       Errors:   On error, a non-zero error code is returned

    See also:    fpFStatFS (1571   ), fpStat (1547   )


                                                                                1572

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.15          fpSystem

    Synopsis:    Execute and feed command to system shell

Declaration:     function  fpSystem(const  Command:  String)  :  cint
                function  fpSystem(const  Command:  AnsiString)  :  cint

    Visibility:   default

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 FpFork (142  ) or FpExecve (139  )
                calls.

       Errors:   Errors are reported in fpErrNo (94 )

    See also:    POpen (1578   ), Shell (1580   ), #rtl.baseunix.FpFork (142  ), #rtl.baseunix.fpexecve (139  )


                Listing:  ./unixex/ex80.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5 6;


                 u s e s U n i x;


                {   Program       t o  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  * . pp  ') ;
                    S := f p S y s t e m(' l s -  l  * .pp  ' ) ;
                    W r i t e l n ( 'Command        e x i t e d w w i t h s t a t u s :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.16          FSearch

    Synopsis:    Search for file in search path.

Declaration:     function  FSearch(const  path:  AnsiString;dirlist:  Ansistring;
                                           CurrentDirStrategy:  TFSearchOption)  :  AnsiString
                function  FSearch(const  path:  AnsiString;dirlist:  AnsiString)
                                            :  AnsiString

    Visibility:   default

Description:     FSearch searches in DirList, a colon separated list of directories, for a file named Path.  It
                then returns a path to the found file.

                The CurrentDirStrategy determines how the current directory is treated when searching:


                NoCurrentDirectory               Do not search the current directory unless it is specified in the search
                       path.

                CurrentDirectoryFirst               Search the current directory first, before all directories in the search
                       path.

                CurrentDirectoryLast               Search the current directory last, after all directories in the search
                       path

                                                                                1573

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                It is mainly provided to mimic DOS search path behaviour.  Default behaviour is to search
                the current directory first.

       Errors:   An empty string if no such file was found.

    See also:    #rtl.unixutil.FNMatch (1602   )


                Listing:  ./unixex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 6;


                {   Program       t o  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     B a s e U n i x,  Unix   ,  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(f p G e t e n v('PATH   ' ) ) ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.17          fStatFS

    Synopsis:    Retrieve filesystem information from a file descriptor.

Declaration:     function  fStatFS(Fd:  cint;var  Info:  tstatfs)  :  cint

    Visibility:   default

Description:     fStatFS returns in Info information about the filesystem on which the file with file descrip-
                tor fd resides.  Info is of type TStatFS (1598   ).

                The  function  returns  zero  if  the  call  was  succesful,  a  nonzero  value  is  returned  if  the  call
                failed.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                sys__enotdir      A component of  Path is not a directory.

                sys__einval    Invalid character in Path.

                sys__enoent      Path does not exist.

                sys__eaccess     Search permission is denied for component inPath.

                sys__eloop     A circular symbolic link was encountered in Path.

                sys__eio   An error occurred while reading from the filesystem.


    See also:    StatFS (1581   ), #rtl.baseunix.FpLStat (152  )


                Listing:  ./unixex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 0;


                {   Program       t o  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 B a s e U n i x,Unix   , U n i x T y p e;


                 v a r  s  :   s t r i n g;
                        f d  :  c i n t;
                        i n f o :   t s t a t f s;

                                                                                1574

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                 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
                       Fd  := fpOpen     (S  ,O _RDOnly     ) ;
                        i f  (f d >=0)     then
                           b e g i n
                           i f   f p f s t a t f s(f d , @ i n f o)<>0    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 :   ' ,f p g e t e r r n o) ;
                               h a l t ( 1 ) ;
                              end   ;
                           F p C l o s e(f d ) ;
                           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 , ' '' . ') ;
                {  $ i f d e f i n e d(L i n u x)  o r   d e f i n e d(s u n o s)}
                           //   SysV     l i k e.
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f s t y p e) ;
                { $ e l s e}
                           //   BSD    l i k e,   i n c l Mac    OS   X .
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f t y p e) ;
                { $ e n d i f}


                           w r i t e l n ( ' b s i z e     :  ' , i n f o.b s i z e) ;
                           w r i t e l n ( ' b f r e e     :  ' , i n f o.b f r e e) ;
                           w r i t e l n ( ' b a v a i l   :  ' , i n f o.b a v a i l) ;
                           w r i t e l n ( ' f i l e s     :  ' , i n f o.f i l e s) ;
                           w r i t e l n ( ' f f r e e     :  ' , i n f o.f f r e e) ;
                           { $ i f d e f FreeBSD     }
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           { $ e l s e}
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           w r i t e l n ( 'Namelen        :  ' , i n f o.n a m e l e n) ;
                           { $ e n d i f}
                           w r i t e (  'Type    name     o f   f i l e t o  do    f s s t a t.  (q   q u i t s)  : ' ) ;
                           r e a d l n ( s )


                           end  ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.18          fsync

    Synopsis:    Synchronize file's kernel data with disk.

Declaration:     function  fsync(fd:  cint)  :  cint

    Visibility:   default

Description:     Fsync synchronizes the kernel data for file fd (the cache) with the disk.  The call will not
                return till all file data was written to disk.

                If the call was succesfull, 0 is returned.  On failure, a nonzero value is returned.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:

    See also:    FpFLock (1571   )
                                                                                1575

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.19          GetDomainName

    Synopsis:    Return current domain name

Declaration:     function  GetDomainName  :  String

    Visibility:   default

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 (1576   )


                Listing:  ./unixex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   Program       t o  d e m o n s t r a t et h e  GetDomainName            f u n c t i o n. }


                Uses     U n i x;


                 b e g i n
                    W r i t e l n ( 'Domain      name     o f   t h i s m a c h i n e  i s  :  ' ,GetDomainName          ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.20          GetHostName

    Synopsis:    Return host name

Declaration:     function  GetHostName  :  String

    Visibility:   default

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 (1576   )


                Listing:  ./unixex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 0;


                {   Program       t o  d e m o n s t r a t et h e  GetHostName          f u n c t i o n. }


                Uses     u n i x;


                 b e g i n
                    W r i t e l n ( 'Name     o f   t h i s m a c h i n e i s  :   ' ,GetHostName         ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1576

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.21          GetLocalTimezone

    Synopsis:    Return local timzeone information

Declaration:     procedure  GetLocalTimezone(timer:  cint;var  leap_correct:  cint;
                                                           var  leap_hit:  cint)
                procedure  GetLocalTimezone(timer:  cint)

    Visibility:   default

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 (1577   ), ReadTimezoneFile (1579   )
                32.3.22          GetTimezoneFile

    Synopsis:    Return name of timezone information file

Declaration:     function  GetTimezoneFile  :  String

    Visibility:   default

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 (1579   )
                32.3.23          PClose

    Synopsis:    Close file opened with POpen (1578   )

Declaration:     function  PClose(var  F:  File)  :  cint
                function  PClose(var  F:  text)  :  cint

    Visibility:   default

Description:     PClose closes a file opened with POpen (1578   ).  It waits for the command to complete, and
                then returns the exit status of the command.

                For an example, see POpen (1578   )

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function.

    See also:    POpen (1578   )


                                                                                1577

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.24          POpen

    Synopsis:    Pipe file to standard input/output of program

Declaration:     function  POpen(var  F:  text;const  Prog:  Ansistring;rw:  Char)  :  cint
                function  POpen(var  F:  File;const  Prog:  Ansistring;rw:  Char)  :  cint

    Visibility:   default

Description:     POpen runs the command specified in Prog, 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 (1577   ).  The
                result is the same, but PClose returns the exit status of the command Prog.

       Errors:   Extended  error  information  is  returned  by  the  FpGetErrno  (145  )  function.   Errors  are
                essentially those of the Execve, Dup and AssignPipe commands.

    See also:    AssignPipe (1563   ), PClose (1577   )


                Listing:__./unixex/ex37.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 3 7;


                {   Program       t o  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 B a s e U n i x,U n i 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 ga   s h e l l s c r i p t t o   w h i c h 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 b a c k  t o  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/ s h ' ) ;
                    w r i t e l n ( f , 'e c h o  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 , 'e c h o  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 ) ;
                    fpchmod       ( ' t e s t 2 1 a', & 7 5 5 ) ;
                    popen     ( f , ' . /t e s t 2 1 a a r g 1  a r g 2' ,'W  ' ) ;
                    i f  f p g e t e r r n<o>0    then
                         w r i t e l n ( ' e r r o r f r o m  POpen     :   e r r n o :   ' ,  f p g e t e r r n o) ;
                    f o r  i : = 1  t o  1 0  do
                        w r i t e l n( f , 'T h i s  i s   w r i t t e nt o   t h e  p i p e,  and    s h o u l d a p p e a r on   *
 * 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 e ( f ) ) ;
                    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>  t o  r e m o v e 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___.____________________________________________________________________________________________________________*
 *___________

                                                                                1578

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.25          ReadTimezoneFile

    Synopsis:    Read the timezone file and initialize time routines

Declaration:     procedure  ReadTimezoneFile(fn:  String)

    Visibility:   default

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 (1577   ), GetLocalTimezone (1577   )
                32.3.26          SeekDir

    Synopsis:    Seek to position in directory

Declaration:     procedure  SeekDir(p:  pDir;loc:  clong)

    Visibility:   default

Description:     SeekDir sets the directory pointer to the loc-th entry in the directory structure pointed to
                by p.

                For an example, see #rtl.baseunix.fpOpenDir (158  ).

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:

    See also:    #rtl.baseunix.fpCloseDir  (136  ),  #rtl.baseunix.fpReadDir  (162  ),  #rtl.baseunix.fpOpenDir
                (158  ), TellDir (1582   )
                32.3.27          SelectText

    Synopsis:    Wait for event on text file.

Declaration:     function  SelectText(var  T:  Text;TimeOut:  ptimeval)  :  cint
                function  SelectText(var  T:  Text;TimeOut:  cint)  :  cint

    Visibility:   default

Description:     SelectText  executes  the  FpSelect  (165  )  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 #rtl.baseunix.FpSelect (165  ).  SYS_EBADF can also mean that the file wasn't opened.

    See also:    #rtl.baseunix.FpSelect (165  )



                                                                                1579

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.28          Shell

    Synopsis:    Execute and feed command to system shell

Declaration:     function  Shell(const  Command:  String)  :  cint
                function  Shell(const  Command:  AnsiString)  :  cint

    Visibility:   default

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 FpFork (142  ) or FpExecve (139  )
                calls.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:

    See also:    POpen (1578   ), FpSystem (1573   ), #rtl.baseunix.FpFork (142  ), #rtl.baseunix.fpexecve (139  )


                Listing:  ./unixex/ex56.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5 6;


                 u s e s U n i x;


                {   Program       t o  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  * . pp  ') ;
                    S := S h e l l  ( 'l s  - l   * .pp  ' ) ;
                    W r i t e l n ( 'Command        e x i t e d w w i t h s t a t u s :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.29          SigRaise

    Synopsis:    Raise a signal (send to current process)

Declaration:     procedure  SigRaise(sig:  Integer)

    Visibility:   default

Description:     SigRaise sends a Sig signal to the current process.

       Errors:   None.

    See also:    #rtl.baseunix.FpKill (150  ), #rtl.baseunix.FpGetPid (147  )


                Listing:  ./unixex/ex65.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 6 4;


                {   Program       t o  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 Unix   , B a s e U n i x;


                Var
                      oa , na   :   P S i g A c t i o n r e;c
                                                                                1580

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                 P r o c e d u r eDoSig    ( 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 gs i g n a l:  ' , s i g) ;
                end   ;


                 b e g i n
                      new  ( na ) ;
                      new  ( oa ) ;
                      na ^ . s a _h a n d l e r:= S i g A c t i o n H a n d l e(r@DoSig   ) ;
                      f i l l c h a r(na ^ .Sa _Mask     , s i z e o f(na ^ .Sa _Mask     ) , # 0 ) ;
                      na ^ . S a _F l a g s: = 0 ;
                      { $ i f d e f L i n u x}
                      //   t h i s  member      i s  l i n u x  o n l y,  and    a f a i k  e v e n t h e r e  a r c a n e
                      na ^ . S a _R e s t o r e r:=N i l ;
                      { $ e n d i f}
                      i f  f p S i g A c t i o(nS i g U s r 1,na  ,oa )<>0     then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , f p g e t e r r n)o;
                         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 t o  s e l f. ' ) ;
                      S i g R a i s e(s i g u s r 1) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.30          StatFS

    Synopsis:    Retrieve filesystem information from a path.

Declaration:     function  StatFS(Path:  pchar;var  Info:  tstatfs)  :  cint
                function  StatFS(Path:  ansistring;var  Info:  tstatfs)  :  cint

    Visibility:   default

Description:     StatFS  returns  in  Info  information  about  the  filesystem  on  which  the  file  Path  resides.
                Info is of type TStatFS (1598   ).

                The  function  returns  zero  if  the  call  was  succesful,  a  nonzero  value  is  returned  if  the  call
                failed.

       Errors:   Extended error information is returned by the FpGetErrno (145  ) function:


                sys__enotdir      A component of  Path is not a directory.

                sys__einval    Invalid character in Path.

                sys__enoent      Path does not exist.

                sys__eaccess     Search permission is denied for component inPath.

                sys__eloop     A circular symbolic link was encountered in Path.

                sys__eio   An error occurred while reading from the filesystem.


    See also:    #rtl.baseunix.FpStat (173  ), #rtl.baseunix.FpLStat (152  )


                Listing:  ./unixex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 0;


                {   Program       t o  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.  }



                                                                                1581

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________


                 u s e s B a s e U n i x,Unix   , U n i x T y p e;


                 v a r  s  :   s t r i n g;
                        f d  :  c i n t;
                        i n f o :   t 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
                       Fd  := fpOpen     (S  ,O _RDOnly     ) ;
                        i f  (f d >=0)     then
                           b e g i n
                           i f   f p f s t a t f s(f d , @ i n f o)<>0    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 :   ' ,f p g e t e r r n o) ;
                               h a l t ( 1 ) ;
                              end   ;
                           F p C l o s e(f d ) ;
                           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 , ' '' . ') ;
                {  $ i f d e f i n e d(L i n u x)  o r   d e f i n e d(s u n o s)}
                           //   SysV     l i k e.
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f s t y p e) ;
                { $ e l s e}
                           //   BSD    l i k e,   i n c l Mac    OS   X .
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f t y p e) ;
                { $ e n d i f}


                           w r i t e l n ( ' b s i z e     :  ' , i n f o.b s i z e) ;
                           w r i t e l n ( ' b f r e e     :  ' , i n f o.b f r e e) ;
                           w r i t e l n ( ' b a v a i l   :  ' , i n f o.b a v a i l) ;
                           w r i t e l n ( ' f i l e s     :  ' , i n f o.f i l e s) ;
                           w r i t e l n ( ' f f r e e     :  ' , i n f o.f f r e e) ;
                           { $ i f d e f FreeBSD     }
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           { $ e l s e}
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           w r i t e l n ( 'Namelen        :  ' , i n f o.n a m e l e n) ;
                           { $ e n d i f}
                           w r i t e (  'Type    name     o f   f i l e t o  do    f s s t a t.  (q   q u i t s)  : ' ) ;
                           r e a d l n ( s )


                           end  ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________

                32.3.31          TellDir

    Synopsis:    Return current location in a directory

Declaration:     function  TellDir(p:  pDir)  :  TOff

    Visibility:   default

                                                                                1582

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
Description:     TellDir returns the current location in the directory structure pointed to by p.  It returns
                -1 on failure.

                For an example, see #rtl.baseunix.fpOpenDir (158  ).

       Errors:

    See also:    #rtl.baseunix.fpCloseDir  (136  ),  #rtl.baseunix.fpReadDir  (162  ),  #rtl.baseunix.fpOpenDir
                (158  ), SeekDir (1579   )
                32.3.32          WaitProcess

    Synopsis:    Wait for process to terminate.

Declaration:     function  WaitProcess(Pid:  cint)  :  cint

    Visibility:   default

Description:     WaitProcess waits for process PID to exit.  WaitProcess is equivalent to the #rtl.baseunix.FpWaitPID
                (181  ) call:


                FpWaitPid(PID,@result,0)


                Handles of Signal interrupts (errno=EINTR), and returns the Exitcode of Process PID (>=0)
                or -Status if it was terminated

       Errors:   None.

    See also:    #rtl.baseunix.FpWaitPID (181  ), #rtl.baseunix.WTERMSIG (184  ), #rtl.baseunix.WSTOPSIG
                (184  ), #rtl.baseunix.WIFEXITED (183  ), WIFSTOPPED (1583   ), #rtl.baseunix.WIFSIGNALED
                (183  ), W_EXITCODE (1583   ), W_STOPCODE (1584   ), #rtl.baseunix.WEXITSTATUS (183  )
                32.3.33          WIFSTOPPED

    Synopsis:    Check whether the process is currently stopped.

Declaration:     function  WIFSTOPPED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFSTOPPED  checks  Status  and  returns  true  if  the  process  is  currently  stopped.  This  is
                only possible if WUNTRACED was specified in the options of FpWaitPID (181  ).

    See also:    #rtl.baseunix.FpWaitPID  (181  ),  WaitProcess  (1583   ),  #rtl.baseunix.WTERMSIG  (184  ),
                #rtl.baseunix.WSTOPSIG (184  ), #rtl.baseunix.WIFEXITED (183  ), #rtl.baseunix.WIFSIGNALED
                (183  ), W_EXITCODE (1583   ), W_STOPCODE (1584   ), #rtl.baseunix.WEXITSTATUS (183  )
                32.3.34          W__EXITCODE

    Synopsis:    Construct an exit status based on an return code and signal.

Declaration:     function  W_EXITCODE(ReturnCode:  Integer;Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_EXITCODE combines ReturnCode and Signal to a status code fit for WaitPid.

    See also:    #rtl.baseunix.FpWaitPID  (181  ),  WaitProcess  (1583   ),  #rtl.baseunix.WTERMSIG  (184  ),
                #rtl.baseunix.WSTOPSIG (184  ), #rtl.baseunix.WIFEXITED (183  ), WIFSTOPPED (1583   ),
                #rtl.baseunix.WIFSIGNALED (183  ), W_EXITCODE (1583   ), W_STOPCODE (1584   ), #rtl.baseunix.WEXITSTATUS
                (183  )



                                                                                1583

                ______________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________
                32.3.35          W__STOPCODE

    Synopsis:    Construct an exit status based on a signal.

Declaration:     function  W_STOPCODE(Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_STOPCODE constructs an exit status based on Signal, which will cause WIFSIGNALED
                (183  ) to return True

    See also:    #rtl.baseunix.FpWaitPID  (181  ),  WaitProcess  (1583   ),  #rtl.baseunix.WTERMSIG  (184  ),
                #rtl.baseunix.WSTOPSIG (184  ), #rtl.baseunix.WIFEXITED (183  ), WIFSTOPPED (1583   ),
                #rtl.baseunix.WIFSIGNALED (183  ), W_EXITCODE (1583   ), #rtl.baseunix.WEXITSTATUS
                (183  )


                                                                                1584


Chapter   33


Reference   for   unit   'unixtype'
33.1          Overview


The unixtype unit contains the definitions of basic unix types.  It was initially implemented
by Marco van de Voort.

When porting to a new unix platform, this unit should be adapted to the sizes and conven-
tions of the platform to which the compiler is ported.
33.2          Constants,  types  and  variables



33.2.1         Constants

ARG_MAX  =  131072


Max number of command-line arguments.


NAME_MAX  =  255


Max length (in bytes) of filename


PATH_MAX  =  4095


Max length (in bytes) of pathname


Prio_PGrp  =  1


rtl.unix.fpGetPriority (1585   ) option:  Get process group priority.


Prio_Process  =  0


#rtl.unix.fpGetPriority (1547   ) option:  Get process priority.


Prio_User  =  2


#rtl.unix.fpGetPriority (1547   ) option:  Get user priority.



                                                            1585

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
SIG_MAXSIG  =  128


Maximum signal number.


SYS_NMLN  =  65


Max system namelength


_PTHREAD_MUTEX_ADAPTIVE_NP  =  3


Mutex options:


_PTHREAD_MUTEX_DEFAULT  =  _PTHREAD_MUTEX_NORMAL


Mutex options:


_PTHREAD_MUTEX_ERRORCHECK  =  _PTHREAD_MUTEX_ERRORCHECK_NP


Mutex options:


_PTHREAD_MUTEX_ERRORCHECK_NP  =  2


Mutex options:  double lock returns an error code.


_PTHREAD_MUTEX_FAST_NP  =  _PTHREAD_MUTEX_ADAPTIVE_NP


Mutex options:  Fast mutex


_PTHREAD_MUTEX_NORMAL  =  _PTHREAD_MUTEX_TIMED_NP


Mutex options:


_PTHREAD_MUTEX_RECURSIVE  =  _PTHREAD_MUTEX_RECURSIVE_NP


Mutex options:


_PTHREAD_MUTEX_RECURSIVE_NP  =  1


Mutex options:  recursive mutex


_PTHREAD_MUTEX_TIMED_NP  =  0


Mutex options:  ?
33.2.2         Types

cbool  =  longbool


Boolean type
                                                                1586

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
cchar  =  cint8


C type:  8-bit signed integer


cdouble  =  double


Double precision real format.


cfloat  =  single


Floating-point real format


cint  =  cint32


C type:  integer (natural size)


cint16  =  SmallInt


C type:  16 bits sized, signed integer.


cint32  =  LongInt


C type:  32 bits sized, signed integer.


cint64  =  Int64


C type:  64 bits sized, signed integer.


cint8  =  ShortInt


C type:  8 bits sized, signed integer.


clock_t  =  culong


Clock ticks type


clong  =  LongInt


C type:  long signed integer (double sized)


clongdouble  =  extended


Usually translates to an extended, but is CPU dependent.


clonglong  =  cint64


C type:  64-bit (double long) signed integer.


cschar  =  cint8


Signed character type



                                                                1587

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
cshort  =  cint16


C type:  short signed integer (half sized)


csigned  =  cint


csigned is an alias for cint (1587   ).


csint  =  cint32


Signed integer


cslong  =  LongInt


The size is CPU dependent.


cslonglong  =  cint64


cslonglong is an alias for clonglong (1587   ).


csshort  =  cint16


Short signed integer type


cuchar  =  cuint8


C type:  8-bit unsigned integer


cuint  =  cuint32


C type:  unsigned integer (natural size)


cuint16  =  Word


C type:  16 bits sized, unsigned integer.


cuint32  =  LongWord


C type:  32 bits sized, unsigned integer.


cuint64  =  qword


C type:  64 bits sized, unsigned integer.


cuint8  =  Byte


C type:  8 bits sized, unsigned integer.


culong  =  cardinal


C type:  long unsigned integer (double sized)



                                                                1588

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
culonglong  =  cuint64


C type:  64-bit (double long) unsigned integer.


cunsigned  =  cuint


Alias for #rtl.unixtype.cuint (1588   )


cushort  =  cuint16


C type:  short unsigned integer (half sized)


dev_t  =  cuint64


Device descriptor type.


gid_t  =  cuint32


Group ID type.


ino64_t  =  cuint64


ino64_t is an inode type capable of containing 64-bit inodes.


ino_t  =  clong


Inode type.


ipc_pid_t  =  cushort


Process ID


kDev_t  =  cushort


Kernel device type


mbstate_t  =  record
   __count  :  cint;
   __value  :  mbstate_value_t;
end
This type should never be used directly.


mbstate_value_t  =  record
end
This type should never be used directly.  It is part of the mbstate_t (1589   ) type.


mode_t  =  cuint32



                                                                1589

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
Inode mode type.


nlink_t  =  cuint32


Number of links type.


off_t  =  cint


Offset type.


pcbool  =  ^cbool


Pointer to boolean type cbool (1586   )


pcchar  =  ^cchar


Pointer to #rtl.UnixType.cchar (1587   )


pcdouble  =  ^cdouble


Pointer to cdouble (1587   ) type.


pcfloat  =  ^cfloat


Pointer to cfloat (1587   ) type.


pcint  =  ^cint


Pointer to cInt (1587   ) type.


pcint16  =  ^cint16


Pointer to 16-bit signed integer type


pcint32  =  ^cint32


Pointer to signed 32-bit integer type


pcint64  =  ^cint64


Pointer to signed 64-bit integer type


pcint8  =  ^cint8


Pointer to 8-bits signed integer type


pClock  =  ^clock_t


Pointer to TClock (1596   ) type.


pclong  =  ^clong



                                                                1590

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
Pointer to cLong (1587   ) type.


pclongdouble  =  ^clongdouble


Pointer to the long double type clongdouble (1587   )


pclonglong  =  ^clonglong


Pointer to longlong type.


pcschar  =  ^cschar


Pointer to character type cschar (1587   ).


pcshort  =  ^cshort


Pointer to cShort (1588   ) type.


pcsigned  =  ^csigned


Pointer to signed integer type csigned (1588   ).


pcsint  =  ^csint


Pointer to signed integer type csint (1588   )


pcslong  =  ^cslong


Pointer ot the signed long cslong (1588   )


pcslonglong  =  ^cslonglong


Pointer to Signed longlong type cslonglong (1588   )


pcsshort  =  ^csshort


Pointer to short signed integer type csshort (1588   )


pcuchar  =  ^cuchar


Pointer to #rtl.UnixType.cuchar (1588   )


pcuint  =  ^cuint


Pointer to cUInt (1588   ) type.


pcuint16  =  ^cuint16


Pointer to 16-bit unsigned integer type


pcuint32  =  ^cuint32



                                                                1591

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
Pointer to unsigned 32-bit integer type


pcuint64  =  ^cuint64


Pointer to unsigned 64-bit integer type


pcuint8  =  ^cuint8


Pointer to 8-bits unsigned integer type


pculong  =  ^culong


Pointer to cuLong (1588   ) type.


pculonglong  =  ^culonglong


Unsigned longlong type


pcunsigned  =  ^cunsigned


Pointer to #rtl.unixtype.cunsigned (1589   )


pcushort  =  ^cushort


Pointer to cuShort (1589   ) type.


pDev  =  ^dev_t


Pointer to TDev (1596   ) type.


pGid  =  ^gid_t


Pointer to TGid (1596   ) type.


pid_t  =  cint


Process ID type.


pIno  =  ^ino_t


Pointer to TIno (1597   ) type.


pIno64  =  ^ino64_t


Pointer to ino64_t (1589   )


pkDev  =  ^kDev_t


Pointer to TkDev (1597   ) type.


pmbstate_t  =  ^mbstate_t



                                                                1592

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
Pointer to mbstate_t (1585   ) type


pMode  =  ^mode_t


Pointer to TMode (1597   ) type.


pnLink  =  ^nlink_t


Pointer to TnLink (1597   ) type.


pOff  =  ^off_t


Pointer to TOff (1597   ) type.


pPid  =  ^pid_t


Pointer to TPid (1597   ) type.


pSize  =  ^size_t


Pointer to TSize (1597   ) type.


psize_t  =  pSize


Pointer to size_t (1585   ) type.


pSockLen  =  ^socklen_t


Pointer to TSockLen (1597   ) type.


pSSize  =  ^ssize_t


Pointer to TsSize (1597   ) type


PStatFS  =  ^TStatfs


Pointer to TStatFS (1598   ) type.


pthread_attr_t  =  record
   __detachstate  :  cint;
   __schedpolicy  :  cint;
   __schedparam  :  sched_param;
   __inheritsched  :  cint;
   __scope  :  cint;
   __guardsize  :  size_t;
   __stackaddr_set  :  cint;
   __stackaddr  :  pointer;
   __stacksize  :  size_t;
end


                                                                1593

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
pthread_attr_t describes the thread attributes.  It should be considered an opaque record,
the names of the fields can change anytime.  Use the appropriate functions to set the thread
attributes.


pthread_condattr_t  =  record
   __dummy  :  cint;
end
pthread_condattr_t describes the attributes of a thread mutex.  It should be considered an
opaque record, the names of the fields can change anytime.


pthread_cond_t  =  record
   __c_lock  :  _pthread_fastlock;
   __c_waiting  :  pointer;
   __padding  :  Array[0..48-1-sizeof(_pthread_fastlock)-sizeof(pointer)-sizeof(clonglong)]  of  Byte;
   __align  :  clonglong;
end
pthread_cond_t describes a thread conditional variable.  It should be considered an opaque
record, the names of the fields can change anytime.


pthread_key_t  =  cuint


Thread local storage key (opaque)


pthread_mutexattr_t  =  record
   __mutexkind  :  cint;
end
pthread_mutexattr_t describes the attributes of a thread mutex.  It should be considered
an opaque record, the names of the fields can change anytime.


pthread_mutex_t  =  record
   __m_reserved  :  cint;
   __m_count  :  cint;
   __m_owner  :  pointer;
   __m_kind  :  cint;
   __m_lock  :  _pthread_fastlock;
end
_pthread_mutex_t describes a thread mutex.  It should be considered an opaque record, the
names of the fields can change anytime.


pthread_rwlockattr_t  =  record
   __lockkind  :  cint;
   __pshared  :  cint;
end

                                                                1594

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
pthread_rwlockattr_t describes the attributes of a lock.  It should be considered an opaque
record, the names of the fields can change anytime.


pthread_rwlock_t  =  record
   __rw_readers  :  cint;
   __rw_writer  :  pointer;
   __rw_read_waiting  :  pointer;
   __rw_write_waiting  :  pointer;
   __rw_kind  :  cint;
   __rw_pshared  :  cint;
end
pthread_rwlock_t describes a lock.  It should be considered an opaque record, the names of
the fields can change anytime.


pthread_t  =  culong


Thread description record


pTime  =  ^time_t


Pointer to TTime (1598   ) type.


ptimespec  =  ^timespec


Pointer to timespec (1596   ) record.


ptimeval  =  ^timeval


Pointer to timeval (1596   ) record.


ptime_t  =  ^time_t


Pointer to time_t (1597   ) type.


pUid  =  ^uid_t


Pointer to TUid (1598   ) type.


pwchar_t  =  ^wchar_t


Pointer to wchar_t (1585   ) type.


sched_param  =  record
   __sched_priority  :  cint;
end
Scheduling parameter description record.
                                                                1595

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
sem_t  =  record
   __sem_lock  :  _pthread_fastlock;
   __sem_value  :  cint;
   __sem_waiting  :  pointer;
end
sem_t describes a thread semaphore.  It should be considered an opaque record, the names
of the fields can change anytime.


size_t  =  cuint32


Size specification type.


socklen_t  =  cuint32


Socket address length type.


ssize_t  =  cint32


Small size type.


TClock  =  clock_t


Alias for clock_t (1587   ) type.


TDev  =  dev_t


Alias for dev_t (1589   ) type.


TGid  =  gid_t


Alias for gid_t (1589   ) type.


timespec  =  packed  record
   tv_sec  :  time_t;
   tv_nsec  :  clong;
end
Record specifying time interval.


timeval  =  packed  record
   tv_sec  :  time_t;
   tv_usec  :  clong;
end
Time specification type.


time_t  =  clong



                                                                1596

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
Time span type


TIno  =  ino_t


Alias for ino_t (1589   ) type.


TIno64  =  ino64_t


Alias for ino64_t (1589   )


TIOCtlRequest  =  cint


Opaque type used in FpIOCtl (149  )


TkDev  =  kDev_t


Alias for kDev_t (1589   ) type.


TMode  =  mode_t


Alias for mode_t (1590   ) type.


TnLink  =  nlink_t


Alias for nlink_t (1590   ) type.


TOff  =  off_t


Alias for off_t (1590   ) type.


TPid  =  pid_t


Alias for pid_t (1592   ) type.


TSize  =  size_t


Alias for size_t (1596   ) type


TSockLen  =  socklen_t


Alias for socklen_t (1596   ) type.


TSSize  =  ssize_t


Alias for ssize_t (1596   ) type


TStatfs  =  packed  record
   fstype  :  cint;
   bsize  :  cint;
   blocks  :  clong;
   bfree  :  clong;



                                                                1597

______________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___
   bavail  :  clong;
   files  :  clong;
   ffree  :  clong;
   fsid  :  Array[0..1]  of  cint;
   namelen  :  clong;
   spare  :  Array[0..5]  of  clong;
end
Record describing a file system in the baseunix.fpstatfs (1585   ) call.


TTime  =  time_t


Alias for TTime (1598   ) type.


TTimeSpec  =  timespec


Alias for TimeSpec (1596   ) type.


TTimeVal  =  timeval


Alias for TimeVal (1596   ) record.


TUid  =  uid_t


Alias for uid_t (1598   ) type.


uid_t  =  cuint32


User ID type


wchar_t  =  cint32


Wide character type.


wint_t  =  cint32


Wide character size type.


_pthread_fastlock  =  record
   __status  :  clong;
   __spinlock  :  cint;
end
_pthread_fastlock  describes  a  thread  mutex.  It  should  be  considered  an  opaque  record,
the names of the fields can change anytime.


                                                                1598


Chapter   34


Reference   for   unit   'unixutil'
34.1          Overview


The UnixUtil unit contains some of the routines that were present in the old Linux unit, but
which do not really belong in the unix (1547   ) or baseunix (94 ) units.

Most of the functions described here have cross-platform counterparts in the SysUtils (1356   )
unit.  It is therefore recommended to use that unit.
34.2          Constants,  types  and  variables



34.2.1         Types

ComStr  =


Command-line string type.


DirStr  =


Filename directory part string type.


ExtStr  =


Filename extension part string type.


NameStr  =


Filename name part string type.


PathStr  =


Filename full path string type.
34.2.2         Variables

Tzseconds  :  LongInt


Seconds west of GMT



                                                            1599

                _______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________
                34.3          Procedures  and  functions



                34.3.1         ArrayStringToPPchar

    Synopsis:    Concert an array of string to an array of null-terminated strings

Declaration:     function  ArrayStringToPPchar(const  S:  Array  of  AnsiString;
                                                              reserveentries:  LongInt)  :  ppchar

    Visibility:   default

Description:     ArrayStringToPPchar creates an array of null-terminated strings that point to strings which
                are the same as the strings in the array S. The function returns a pointer to this array.  The
                array and the strings it contains must be disposed of after being used, because it they are
                allocated on the heap.

                The ReserveEntries parameter tells ArrayStringToPPchar to allocate room at the end of
                the array for another ReserveEntries entries.

       Errors:   If not enough memory is available, an error may occur.

    See also:    StringToPPChar (1605   )
                34.3.2         Basename

    Synopsis:    Return basename of a file

Declaration:     function  Basename(const  path:  PathStr;const  suf:  PathStr)  :  PathStr

    Visibility:   default

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 (1601   )


                Listing:  ./unutilex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   Program       t o  d e m o n s t r a t et h e  BaseName        f u n c t i o n. }


                Uses     Dos   ,Unix   , U n i x U t i l;


                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 p r o g r a m i s   c a l l e d :  ' ,Basename      ( S , ' ') ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                                                                                1600

                _______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________
                34.3.3         Dirname

    Synopsis:    Extract directory part from filename

Declaration:     function  Dirname(const  path:  PathStr)  :  PathStr

    Visibility:   default

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 (1600   )


                Listing:  ./unutilex/ex47.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   Program       t o  d e m o n s t r a t et h e  DirName       f u n c t i o n. }


                Uses     Dos   ,Unix   , U n i x U t i l;


                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 p r o g r a m i s  i n   d i r e c t o r y:   ' ,Dirname     ( S ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                34.3.4         EpochToLocal

    Synopsis:    Convert epoch time to local time

Declaration:     procedure  EpochToLocal(epoch:  LongInt;var  year:  Word;var  month:  Word;
                                                     var  day:  Word;var  hour:  Word;var  minute:  Word;
                                                     var  second:  Word)

    Visibility:   default

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:    LocalToEpoch (1604   )


                Listing:  ./unutilex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  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     B a s e U n i x,Unix   , U n i x U t i l;


                Var    Year    ,month    , day  , h o u r,m i n u t e, s e c o n d s :  Word   ;



                                                                                1601

                _______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________


                 b e g i n
                    E p o c h T o L o c a l(FPTime     , 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 td a t e  :   ' ,Day  : 2 , '/ ' ,Month    : 2 , '/ ' ,Y e a r : 4 ) ;
                    W r i t e l n ( ' C u r r e n tt i m e  :   ' ,Hour   : 2 , ': ' ,m i n u t e: 2 ,' : ' ,s e c o n d s: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                34.3.5         FNMatch

    Synopsis:    Check whether filename matches wildcard specification

Declaration:     function  FNMatch(const  Pattern:  String;const  Name:  String)  :  Boolean

    Visibility:   default

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:    #rtl.unix.FSearch (1573   )


                Listing:  ./unutilex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   Program       t o  d e m o n s t r a t et h e  FNMatch       f u n c t i o n. }


                Uses      u n i x u t i;l


                    P r o c e d u r eTestMatch       ( 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  n o t  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___.____________________________________________________________________________________________________________*
 *___________


                                                                                1602

                _______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________
                34.3.6         FSplit

    Synopsis:    Split filename into path, name and extension

Declaration:     procedure  FSplit(const  Path:  PathStr;var  Dir:  DirStr;var  Name:  NameStr;
                                           var  Ext:  ExtStr)

    Visibility:   default

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:    #rtl.unix.FSearch (1573   )


                Listing:  ./unutilex/ex67.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                 u s e s U n i x U t i l;


                {   Program       t o  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    ,E x t   :  s t r i n g;


                 b e g i n
                    F S p l i t(ParamStr      ( 1 ) ,Path   ,Name    , E x t) ;
                    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: ' ,E x t ) ;
                end___.____________________________________________________________________________________________________________*
 *___________

                34.3.7         GetFS

    Synopsis:    Return file selector

Declaration:     function  GetFS(var  T:  Text)  :  LongInt
                function  GetFS(var  F:  File)  :  LongInt

    Visibility:   default

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 #rtl.baseunix.fpSelect
                (165  ) call or so.

       Errors:   In case the file was not opened, then -1 is returned.

    See also:    #rtl.baseunix.fpSelect (165  )


                Listing:  ./unutilex/ex34.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  S e l e c t T e x tf u n c t i o n.  }


                Uses     U n i x;



                                                                                1603

                _______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________


                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    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  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 }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s< ENTER    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                    t v .t v _s e c : = 2 ;
                    t v .t v _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___.____________________________________________________________________________________________________________*
 *___________

                34.3.8         GregorianToJulian

    Synopsis:    Converts a gregorian date to a julian date

Declaration:     function  GregorianToJulian(Year:  LongInt;Month:  LongInt;Day:  LongInt)
                                                             :  LongInt

    Visibility:   default

Description:     GregorianToJulian takes a gregorian date and converts it to a Julian day.

       Errors:   None.

    See also:    JulianToGregorian (1604   )
                34.3.9         JulianToGregorian

    Synopsis:    Converts a julian date to a gregorian date

Declaration:     procedure  JulianToGregorian(JulianDN:  LongInt;var  Year:  Word;
                                                             var  Month:  Word;var  Day:  Word)

    Visibility:   default

Description:     JulianToGregorian takes a julian day and converts it to a gregorian date.  (Start of the
                Julian Date count is from 0 at 12 noon 1 JAN -4712 (4713 BC),)

       Errors:   None.

    See also:    GregorianToJulian (1604   )
                34.3.10          LocalToEpoch

    Synopsis:    Convert local time to epoch (unix) time

Declaration:     function  LocalToEpoch(year:  Word;month:  Word;day:  Word;hour:  Word;
                                                   minute:  Word;second:  Word)  :  LongInt

    Visibility:   default



                                                                                1604

                _______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________
Description:     Converts  the  Local  time  to  epoch  time  (=Number  of  seconds  since  00:00:00  ,  January  1,
                1970 ).

       Errors:   None

    See also:    EpochToLocal (1601   )


                Listing:  ./unutilex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  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     U n i x U t i l;


                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     (  'Y e a r       :   ') ; r e a d l n(Y e a r) ;
                    Write     (  'Month         :   ') ; r e a d l n(Month    ) ;
                    Write     (  'Day           :   ') ; r e a d l n(Day  ) ;
                    Write     (  'Hour          :   ') ; r e a d l n(Hour   ) ;
                    Write     (  'M i n u t e   :   ') ; r e a d l n(M i n u t e) ;
                    Write     (  'S e o n d s   :   ') ; r e a d l n(S e c o n d) ;
                    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___.____________________________________________________________________________________________________________*
 *___________

                34.3.11          StringToPPChar

    Synopsis:    Split string in list of null-terminated strings

Declaration:     function  StringToPPChar(S:  PChar;ReserveEntries:  Integer)  :  ppchar
                function  StringToPPChar(var  S:  String;ReserveEntries:  Integer)  :  ppchar
                function  StringToPPChar(var  S:  AnsiString;ReserveEntries:  Integer)
                                                        :  ppchar

    Visibility:   default

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.

                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:    ArrayStringToPPchar (1600   ), #rtl.baseunix.FpExecve (139  )


                Listing:  ./unutilex/ex70.pp


                                                                                1605

_______________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________________________*
 *___
______________________________________________________________________________________________________________________________
Program       E x a m p l e 7 0;


{   Program       t o  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     U n i x U t i l;


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 ea t  end  .
    S :=  'T h i s  i s  a   s t r i n g w i t h w o r d s.   ';
    P := S t r i n g T o P P C h a(rS, 0 ) ;
    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(P c h a r) ) ;
end___._______________________________________________________________________________________________________________________

                                                                1606


Chapter   35


Reference   for   unit   'video'
35.1          Examples  utility  unit


The examples in this section make use of the unit vidutil, which contains the TextOut func-
tion.  This function writes a text to the screen at a given location.  It looks as follows:
35.2          Writing  a  custom  video  driver


Writing a custom video driver is not difficult, and generally means implementing a couple of
functions, which whould be registered with the SetVideoDriver (1625   ) function.  The various
functions that can be implemented are located in the TVideoDriver (1615   ) record:


TVideoDriver  =  Record
    InitDriver             :  Procedure;
    DoneDriver             :  Procedure;
    UpdateScreen          :  Procedure(Force  :  Boolean);
    ClearScreen            :  Procedure;
    SetVideoMode          :  Function  (Const  Mode  :  TVideoMode)  :  Boolean;
    GetVideoModeCount  :  Function  :  Word;
    GetVideoModeData    :  Function(Index  :  Word;  Var  Data  :  TVideoMode)  :  Boolean;
    SetCursorPos          :  procedure  (NewCursorX,  NewCursorY:  Word);
    GetCursorType        :  function  :  Word;
    SetCursorType        :  procedure  (NewType:  Word);
    GetCapabilities     :  Function  :  Word;
end;


Not  all  of  these  functions  must  be  implemented.   In  fact,  the  only  absolutely  necessary
function to write a functioning driver is the UpdateScreen function.  The general calls in the
Video unit will check which functionality is implemented by the driver.

The functionality of these calls is the same as the functionality of the calls in the video unit,
so the expected behaviour can be found in the previous section.  Some of the calls, however,
need some additional remarks.


InitDriver        Called by InitVideo, this function should initialize any data structures needed
        for  the  functionality  of  the  driver,  maybe  do  some  screen  initializations.   The  func-
        tion  is  guaranteed  to  be  called  only  once;  It  can  only  be  called  again  after  a  call  to



                                                            1607

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___
       DoneVideo.  The variables ScreenWidth and ScreenHeight should be initialized cor-
       rectly after a call to this function, as the InitVideo call will initialize the VideoBuf
       and OldVideoBuf arrays based on their values.

DoneDriver          This should clean up any structures that have been initialized in the InitDriver
       function.  It should possibly also restore the screen as it was before the driver was ini-
       tialized.   The  VideoBuf  and  OldVideoBuf  arrays  will  be  disposed  of  by  the  general
       DoneVideo call.

UpdateScreen           This  is  the  only  required  function  of  the  driver.   It  should  update  the
       screen based on the VideoBuf array's contents.  It can optimize this process by com-
       paring  the  values  with  values  in  the  OldVideoBuf  array.  After  updating  the  screen,
       the UpdateScreen procedure should update the OldVideoBuf by itself.  If the Force
       parameter is True, the whole screen should be updated, not just the changed values.

ClearScreen         If  there  is  a  faster  way  to  clear  the  screen  than  to  write  spaces  in  all  char-
       acter  cells,  then  it  can  be  implemented  here.  If  the  driver  does  not  implement  this
       function,  then  the  general  routines  will  write  spaces  in  all  video  cells,  and  will  call
       UpdateScreen(True).

SetVideoMode            Should set the desired video mode,  if available.  It should return True if
       the mode was set, False if not.

GetVideoModeCount                  Should return the number of supported video modes.  If no modes
       are supported, this function should not be implemented; the general routines will return
       1.  (for the current mode)

GetVideoModeData                 Should return the data for the Index-th mode; Index is zero based.
       The  function  should  return  true  if  the  data  was  returned  correctly,  false  if  Index
       contains  an  invalid  index.   If  this  is  not  implemented,  then  the  general  routine  will
       return the current video mode when Index equals 0.

GetCapabilities           If  this  function  is  not  implemented,  zero  (i.e.   no  capabilities)  will  be
       returned by the general function.


The  following  unit  shows  how  to  override  a  video  driver,  with  a  driver  that  writes  debug
information to a file.  The unit can be used in any of the demonstration programs, by simply
including it in the uses clause.  Setting DetailedVideoLogging to True will create a more
detailed log (but will also slow down functioning)
35.3          Overview


The  Video  unit  implements  a  screen  access  layer  which  is  system  independent.   It  can  be
used  to  write  on  the  screen  in  a  system-independent  way,  which  should  be  optimal  on  all
platforms for which the unit is implemented.

The  working  of  the  Video  is  simple:   After  calling  InitVideo  (1623   ),  the  array  VideoBuf
contains a representation of the video screen of size ScreenWidth*ScreenHeight, going from
left to right and top to bottom when walking the array elements:  VideoBuf[0] contains the
character and color code of the top-left character on the screen.  VideoBuf[ScreenWidth]
contains the data for the character in the first column of the second row on the screen, and
so on.

To  write  to  the  'screen',  the  text  to  be  written  should  be  written  to  the  VideoBuf  array.
Calling UpdateScreen (1626   ) will then cp the text to the screen in the most optimal way.
(an example can be found further on).



                                                                1608

               ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'________________*
 *__________________
               The color attribute is a combination of the foreground and background color, plus the blink
               bit.  The bits describe the various color combinations:


               bits 0-3     The foreground color.  Can be set using all color constants.

               bits 4-6     The background color.  Can be set using a subset of the color constants.

               bit 7    The blinking bit.  If this bit is set, the character will appear blinking.


               Each possible color has a constant associated with it, see the constants section for a list of
               constants.

               The foreground and background color can be combined to a color attribute with the following
               code:


               Attr:=ForeGroundColor  +  (BackGroundColor  shl  4);


               The  color  attribute  can  be  logically  or-ed  with  the  blink  attribute  to  produce  a  blinking
               character:


               Atrr:=Attr  or  blink;


               But not all drivers may support this.

               The  contents  of  the  VideoBuf  array  may  be  modified:  This  is  'writing'  to  the  screen.  As
               soon as everything that needs to be written in the array is in the VideoBuf array,  calling
               UpdateScreen will copy the contents of the array screen to the screen, in a manner that is
               as efficient as possible.

               The  updating  of  the  screen  can  be  prohibited  to  optimize  performance;  To  this  end,  the
               LockScreenUpdate (1623   ) function can be used:  This will increment an internal counter.  As
               long as the counter differs from zero, calling UpdateScreen (1626   ) will not do anything.  The
               counter can be lowered with UnlockScreenUpdate (1626   ).  When it reaches zero, the next call
               to UpdateScreen (1626   ) will actually update the screen.  This is useful when having nested
               procedures that do a lot of screen writing.

               The  video  unit  also  presents  an  interface  for  custom  screen  drivers,  thus  it  is  possible  to
               override the default screen driver with a custom screen driver, see the SetVideoDriver (1625   )
               call.  The current video driver can be retrieved using the GetVideoDriver (1620   ) call.

Remark:         The video unit should not  be used together with the crt unit.  Doing so will result in very
               strange behaviour, possibly program crashes.
               35.4          Constants,  types  and  variables



               35.4.1         Constants

               Black  =  0


               Black color attribute


               Blink  =  128


               Blink attribute


               Blue  =  1



                                                                               1609

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___
Blue color attribute


Brown  =  6


Brown color attribute


cpBlink  =  $0002


Video driver supports blink attribute


cpChangeCursor  =  $0020


Video driver supports changing cursor shape.


cpChangeFont  =  $0008


Video driver supports changing screen font.


cpChangeMode  =  $0010


Video driver supports changing mode


cpColor  =  $0004


Video driver supports color


cpUnderLine  =  $0001


Video driver supports underline attribute


crBlock  =  2


Block cursor


crHalfBlock  =  3


Half block cursor


crHidden  =  0


Hide cursor


crUnderLine  =  1


Underline cursor


Cyan  =  3


Cyan color attribute


DarkGray  =  8



                                                                1610

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___
Dark gray color attribute


errOk  =  0


No error


ErrorCode  :  LongInt  =  ErrOK


Error code returned by the last operation.


ErrorHandler  :  TErrorHandler  =  @DefaultErrorHandler


The  ErrorHandler  variable  can  be  set  to  a  custom-error  handling  function.   It  is  set  by
default to the DefaultErrorHandler (1617   ) function.


ErrorInfo  :  Pointer  =  nil


Pointer to extended error information.


errVioBase  =  1000


Base value for video errors


errVioInit  =  errVioBase  +  1


Video driver initialization error.


errVioNoSuchMode  =  errVioBase  +  3


Invalid video mode


errVioNotSupported  =  errVioBase  +  2


Unsupported video function


FVMaxWidth  =  132


Maximum screen buffer width.


Green  =  2


Green color attribute


iso_codepages  =  [iso01,iso02,iso03,iso04,iso05,iso06,iso07,iso08,iso09,iso10,iso13,iso14,iso15]


iso_codepages is a set containing all code pages that use an ISO encoding.


LightBlue  =  9


Light Blue color attribute



                                                                1611

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___
LightCyan  =  11


Light cyan color attribute


LightGray  =  7


Light gray color attribute


LightGreen  =  10


Light green color attribute


LightMagenta  =  13


Light magenta color attribute


LightRed  =  12


Light red color attribute


LowAscii  =  true


On  some  systems,  the  low  32  values  of  the  DOS  code  page  are  necessary  for  the  ASCII
control codes and cannot be displayed by programs.  If LowAscii is true, you can use the low
32 ASCII values.  If it is false, you must avoid using them.

LowAscii can be implemented either through a constant, variable or property.  You should
under no circumstances assume that you can write to LowAscii, or take its address.


Magenta  =  5


Magenta color attribute


NoExtendedFrame  =  false


The VT100 character set only has line drawing characters consisting of a single line.  If this
value is true, the line drawing characters with two lines will be automatically converted to
single lines.

NoExtendedFrame can be implemented either through a constant, variable or property.  You
should under no circumstances assume that you can write to NoExtendedFrame, or take its
address.


Red  =  4


Red color attribute


ScreenHeight  :  Word  =  0


Current screen height


ScreenWidth  :  Word  =  0



                                                                1612

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___
Current screen Width


vga_codepages  =  [cp437,cp850,cp852,cp866]


vga_codepages is a set containing all code pages that can be considered a normal vga font
(as  in  use  on  early  VGA  cards)  Note  that  KOI8-R  has  line  drawing  characters  in  wrong
place.


vioOK  =  0


No errors occurred


White  =  15


White color attribute


Yellow  =  14


Yellow color attribute
35.4.2         Types

PVideoBuf  =  ^TVideoBuf


Pointer type to TVideoBuf (1614   )


PVideoCell  =  ^TVideoCell


Pointer type to TVideoCell (1614   )


PVideoMode  =  ^TVideoMode


Pointer to TVideoMode (1615   ) record.


Tencoding  =  (cp437,cp850,cp852,cp866,koi8r,iso01,iso02,iso03,iso04,
                      iso05,iso06,iso07,iso08,iso09,iso10,iso13,iso14,iso15)


This type is available under Unix-like operating systems only.


TErrorHandler  =  function(Code:  LongInt;Info:  Pointer)
                                           :  TErrorHandlerReturnValue


The TErrorHandler function is used to register an own error handling function.  It should
be used when installing a custom error handling function, and must return one of the above
values.

Code  should  contain  the  error  code  for  the  error  condition,  and  the  Info  parameter  may
contain any data type specific to the error code passed to the function.


TErrorHandlerReturnValue  =  (errRetry,errAbort,errContinue)


Type used to report and respond to error conditions



                                                                1613

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___

                           Table 35.1:  Enumeration values for type Tencoding


                                           __Value_______Explanation_______________
                                             cp437       Codepage 437
                                             cp850       Codepage 850
                                             cp852       Codepage 852
                                             cp866       Codepage 866
                                             iso01       ISO 8859-1
                                             iso02       ISO 8859-2
                                             iso03       ISO 8859-3
                                             iso04       ISO 8859-4
                                             iso05       ISO 8859-5
                                             iso06       ISO 8859-6
                                             iso07       ISO 8859-7
                                             iso08       ISO 8859-8
                                             iso09       ISO 8859-9
                                             iso10       ISO 8859-10
                                             iso13       ISO 8859-13
                                             iso14       ISO 8859-14
                                             iso15       ISO 8859-15
                                             koi8r       KOI8-R codepage

               Table 35.2:  Enumeration values for type TErrorHandlerReturnValue


                         __Value_______________Explanation___________________________________________
                           errAbort            abort and return error code
                           errContinue         abort without returning an errorcode.
                           errRetry            retry the operation

TVideoBuf  =  Array[0..32759]  of  TVideoCell


The TVideoBuf type represents the screen.


TVideoCell  =  Word


TVideoCell  describes  one  character  on  the  screen.   One  of  the  bytes  contains  the  color
attribute with which the character is drawn on the screen, and the other byte contains the
ASCII code of the character to be drawn.  The exact position of the different bytes in the
record is operating system specific.  On most little-endian systems, the high byte represents
the  color  attribute,  while  the  low-byte  represents  the  ASCII  code  of  the  character  to  be
drawn.


TVideoDriver  =  record
   InitDriver  :  procedure;
   DoneDriver  :  procedure;
   UpdateScreen  :  procedure(Force:  Boolean);
   ClearScreen  :  procedure;
   SetVideoMode  :  function(const  Mode:  TVideoMode)  :  Boolean;
   GetVideoModeCount  :  function  :  Word;
   GetVideoModeData  :  function(Index:  Word;var  Data:  TVideoMode)  :  Boolean;



                                                                1614

____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___
   SetCursorPos  :  procedure(NewCursorX:  Word;NewCursorY:  Word);
   GetCursorType  :  function  :  Word;
   SetCursorType  :  procedure(NewType:  Word);
   GetCapabilities  :  function  :  Word;
end
TVideoDriver record can be used to install a custom video driver, with the SetVideoDriver
(1625   ) call.

An explanation of all fields can be found there.


TVideoMode  =  record
   Col  :  Word;
   Row  :  Word;
   Color  :  Boolean;
end
The TVideoMode record describes a videomode.  Its fields are self-explaining:  Col,Row de-
scribe the number of columns and rows on the screen for this mode.  Color is True if this
mode supports colors, or False if not.


TVideoModeSelector  =  function(const  VideoMode:  TVideoMode;
                                                 Params:  LongInt)  :  Boolean


Video mode selection callback prototype.
35.4.3         Variables

CursorLines  :  Byte


CursorLines is a bitmask which determines which cursor lines are visible and which are not.
Each set bit corresponds to a cursorline being shown.

This variable is not supported on all platforms, so it should be used sparingly.


CursorX  :  Word


Current horizontal position in the screen where items will be written.


CursorY  :  Word


Current vertical position in the screen where items will be written.


external_codepage  :  Tencoding


This variable is for internal use only and should not be used.


internal_codepage  :  Tencoding


This variable is for internal use only and should not be used.



                                                                1615

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                OldVideoBuf  :  PVideoBuf


                The OldVideoBuf contains the state of the video screen after the last screen update.  The
                UpdateScreen (1626   ) function uses this array to decide which characters on screen should be
                updated, and which not.

                Note that the OldVideoBuf array may be ignored by some drivers, so it should not be used.
                The  Array  is  in  the  interface  section  of  the  video  unit  mainly  so  drivers  that  need  it  can
                make use of it.


                ScreenColor  :  Boolean


                ScreenColor indicates whether the current screen supports colors.


                VideoBuf  :  PVideoBuf


                VideoBuf  forms  the  heart  of  the  Video  unit:  This  variable  represents  the  physical  screen.
                Writing to this array and calling UpdateScreen (1626   ) will write the actual characters to the
                screen.


                VideoBufSize  :  LongInt


                Current size of the video buffer pointed to by VideoBuf (1616   )
                35.5          Procedures  and  functions



                35.5.1         ClearScreen

    Synopsis:    Clear the video screen.

Declaration:     procedure  ClearScreen

    Visibility:   default

Description:     ClearScreen  clears  the  entire  screen,  and  calls  UpdateScreen  (1626   )  after  that.   This  is
                done by writing spaces to all character cells of the video buffer in the default color (lightgray
                on black, color attribute \$07).

       Errors:   None.

    See also:    InitVideo (1623   ), UpdateScreen (1626   )


                Listing:  ./videoex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program        t e s t v i d e;o


                 u s e s v i d e o, k e y b o a r d,v i d u t i l;


                Var
                    i   :  l o n g i n t;
                    k   :  T k e y E v e n t;


                 b e g i n
                    I n i t V i d e o;
                    I n i t K e y b o a r;d
                    For    I : = 1  t o  1 0  do



                                                                                1616

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                       TextOut      ( i, i ,   'P r e s s any    k e y  t o   c l e a r s c r e e n') ;
                    U p d a t e S c r e e(nf a l s e) ;
                    K := G e t K e y E v e n t;
                    C l e a r S c r e e;n
                    TextOut     ( 1 , 1 ,' C l e a r e d s c r e e n.  P r e s s any    k e y  t o  end   ') ;
                    U p d a t e S c r e e(nt r u e) ;
                    K := G e t K e y E v e n t;
                    DoneKeyBoard         ;
                    DoneVideo       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.2         DefaultErrorHandler

    Synopsis:    Default error handling routine.

Declaration:     function  DefaultErrorHandler(AErrorCode:  LongInt;AErrorInfo:  Pointer)
                                                                :  TErrorHandlerReturnValue

    Visibility:   default

Description:     DefaultErrorHandler is the default error handler used by the video driver.  It simply sets
                the error code AErrorCode and AErrorInfo in the global variables ErrorCode and ErrorInfo
                and returns errContinue.

       Errors:   None.
                35.5.3         DoneVideo

    Synopsis:    Disable video driver.

Declaration:     procedure  DoneVideo

    Visibility:   default

Description:     DoneVideo  disables  the  Video  driver  if  the  video  driver  is  active.  If  the  videodriver  was
                already disabled or not yet initialized, it does nothing.  Disabling the driver means it will clean
                up any allocated resources, possibly restore the screen in the state it was before InitVideo
                was called.  Particularly, the VideoBuf and OldVideoBuf arrays are no longer valid after a
                call to DoneVideo.

                The DoneVideo should always be called if InitVideo was called.  Failing to do so may leave
                the screen in an unusable state after the program exits.

                For an example, see most other functions.

       Errors:   Normally none.  If the driver reports an error, this is done through the ErrorCode variable.

    See also:    InitVideo (1623   )
                35.5.4         GetCapabilities

    Synopsis:    Get current driver capabilities.

Declaration:     function  GetCapabilities  :  Word

    Visibility:   default


                                                                                1617

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
Description:     GetCapabilities returns the capabilities of the current driver.  It is an or-ed combination
                of the following constants:


                cpUnderLine         Video driver supports underline attribute

                cpBlink     Video driver supports blink attribute

                cpColor     Video driver supports color

                cpChangeFont          Video driver supports changing screen font.

                cpChangeMode            Video driver supports changing mode

                cpChangeCursor            Video driver supports changing cursor shape.


                Note that the video driver should not yet be initialized to use this function.  It is a property
                of the driver.

       Errors:   None.

    See also:    GetCursorType (1618   ), GetVideoDriver (1620   )


                Listing:  ./videoex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t C a p a b i l i t i e sf u n c t i o.n }


                Uses     v i d e o;


                Var
                   W  :  Word   ;


                    P r o c e d u r eT e s t C a p(Cap   :  Word   ;  Msg     :  S t r i n g) ;


                    b e g i n
                       Write    ( Msg  , '   :  ' ) ;
                        I f  (W   and    Cap  = Cap  )   then
                           W r i t e l n(' Yes  ' )
                        e l s e
                           W r i t e l n('No   ') ;
                    end  ;


                 b e g i n
                   W  := G e t C a p a b i l i t i e;s
                    W r i t e l n(' V i d e o d r i v e r s u p p o r t s f o l l o w i n g f u n c t i o n a l i t'y) ;
                    T e s t C a p(c p U n d e r L i n,e' U n d e r l i n e dc h a r a c t e r s') ;
                    T e s t C a p(c p B l i n k,' B l i n k i n g c h a r a c t e r's) ;
                    T e s t C a p(c p C o l o r,' C o l o r c h a r a c t e r s') ;
                    T e s t C a p(cpChangeFont         , 'C h a n g i n g f o n t' ) ;
                    T e s t C a p(cpChangeMode         , 'C h a n g i n g v i d e o mode    ') ;
                    T e s t C a p(c p C h a n g e C u r s o,r'C h a n g i n g c u r s o r s h a p e') ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.5         GetCursorType

    Synopsis:    Get screen cursor type

Declaration:     function  GetCursorType  :  Word

    Visibility:   default



                                                                                1618

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
Description:     GetCursorType returns the current cursor type.  It is one of the following values:


                crHidden      Hide cursor

                crUnderLine        Underline cursor

                crBlock     Block cursor

                crHalfBlock       Half block cursor


                Note that not all drivers support all types of cursors.

       Errors:   None.

    See also:    SetCursorType (1624   ), GetCapabilities (1617   )


                Listing:  ./videoex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t C u r s o r T y p ef u n c t i o n. }


                Uses     v i d e o, k e y b o a r d,v i d u t i l;


                Const
                    C u r s o r t y p e s:  A r r a y[ c r H i d d e n. .c r H a l f B l o c]k o f  s t r i n g =
                        ( 'H i d d e n' ,' U n d e r L i n e',' B l o c k', ' H a l f B l o c k') ;


                 b e g i n
                    I n i t V i d e o;
                    I n i t K e y b o a r;d
                    TextOut     ( 1 , 1 ,' C u r s o r t y p e:   '+ C u r s o r T y p e[sG e t C u r s o r T y p]e) ;
                    TextOut     ( 1 , 2 ,' P r e s s any    k e y  t o   e x i t.' ) ;
                    U p d a t e S c r e e(nF a l s e) ;
                    G e t K e y E v e n;t
                    DoneKeyboard         ;
                    DoneVideo       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.6         GetLockScreenCount

    Synopsis:    Get the screen lock update count.

Declaration:     function  GetLockScreenCount  :  Integer

    Visibility:   default

Description:     GetLockScreenCount returns the current lock level.  When the lock level is zero, a call to
                UpdateScreen (1626   ) will actually update the screen.

       Errors:   None.

    See also:    LockScreenUpdate (1623   ), UnlockScreenUpdate (1626   ), UpdateScreen (1626   )


                Listing:  ./videoex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t L o c k S c r e e n C o u nftu n c t i o n. }
                                                                                1619

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                Uses     v i d e o, k e y b o a r d,v i d u t i l;


                Var
                    I   :  L o n g i n t;
                    S   :  S t r i n g;


                 b e g i n
                    I n i t V i d e o;
                    I n i t K e y b o a r;d
                    TextOut     ( 1 , 1 ,' P r e s s k e y   t i l l new    t e x t  a p p e a r s.') ;
                    U p d a t e S c r e e(nF a l s e) ;
                    Randomize       ;
                    For    I : = 0  t o  Random    ( 1 0 ) + 1 do
                        L o c k S c r e e n U p d a t;e
                    I : = 0 ;
                    While     G e t L o c k S c r e e n C o u n<t>0  do
                        b e g i n
                        I n c( I) ;
                        S t r( I, S ) ;
                        U n l o c k S c r e e n U p d a;t e
                       G e t K e y E v e n t;
                       TextOut      ( 1 , 1 ,'U n L o c k S c r e e n U p d a thead   t o  be    c a l l e d '+ S + '  t i m e s' )*
 * ;
                        U p d a t e S c r e e(nF a l s e) ;
                       end   ;
                    TextOut     ( 1 , 2 ,' P r e s s any    k e y  t o  end   . ') ;
                    U p d a t e S c r e e(nF a l s e) ;
                    G e t K e y E v e n;t
                    DoneKeyboard         ;
                    DoneVideo       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.7         GetVideoDriver

    Synopsis:    Get a copy of the current video driver.

Declaration:     procedure  GetVideoDriver(var  Driver:  TVideoDriver)

    Visibility:   default

Description:     GetVideoMode returns the settings of the currently active video mode.  The row,col fields
                indicate  the  dimensions  of  the  current  video  mode,  and  Color  is  true  if  the  current  video
                supports colors.

       Errors:   None.

    See also:    SetVideoMode (1625   ), GetVideoModeData (1622   )


                Listing:  ./videoex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   Program       t o  d e m o n s t r a t et h e  GetVideoMode           f u n c t i o n. }


                Uses     v i d e o, k e y b o a r d,v i d u t i l;


                Var
                   M    :  TVideoMode        ;
                    S   :  S t r i n g;



                                                                                1620

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________


                 b e g i n
                    I n i t V i d e o;
                    I n i t K e y b o a r;d
                    GetVideoMode         (M  ) ;
                    i f  M . C o l o r then
                       TextOut      ( 1 , 1 ,'C u r r e n t mode     h a s  c o l o r')
                    e l s e
                       TextOut      ( 1 , 1 ,'C u r r e n t mode     d o e s  n o t  h a v e c o l o r' ) ;
                    S t r(M  .Row   ,S ) ;
                    TextOut     ( 1 , 2 ,' Number      o f  r o w s       :   '+ S ) ;
                    S t r(M  .Col   ,S ) ;
                    TextOut     ( 1 , 3 ,' Number      o f  c o l u m n s :   '+ S ) ;
                    T e x t o u t( 1 , 4 ,'P r e s s any    k e y  t o   e x i t.' ) ;
                    U p d a t e S c r e e(nF a l s e) ;
                    G e t K e y E v e n;t
                    DoneKeyboard         ;
                    DoneVideo       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.8         GetVideoMode

    Synopsis:    Return current video mode

Declaration:     procedure  GetVideoMode(var  Mode:  TVideoMode)

    Visibility:   default

Description:     Return current video mode
                35.5.9         GetVideoModeCount

    Synopsis:    Get the number of video modes supported by the driver.

Declaration:     function  GetVideoModeCount  :  Word

    Visibility:   default

Description:     GetVideoModeCount returns the number of video modes that the current driver supports.
                If the driver does not support switching of modes, then 1 is returned.

                This  function  can  be  used  in  conjunction  with  the  GetVideoModeData  (1622   )  function  to
                retrieve data for the supported video modes.

       Errors:   None.

    See also:    GetVideoModeData (1622   ), GetVideoMode (1621   )


                Listing:  ./videoex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  GetVideoModeCount               f u n c t i o n. }


                Uses     v i d e o, k e y b o a r d,v i d u t i l;


                 P r o c e d u r eDumpMode        (M   :  TVideoMode        ;  I n d e x  :  I n t e g e r) ;
                                                                                1621

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                Var
                  S   :  S t r i n g;


                 b e g i n
                    S t r( I n d e x: 2 ,S ) ;
                    i n c( I n d e x) ;
                    TextOut     ( 1 ,I n d e x, ' Data     f o r mode     '+ S + ' :   ') ;
                    i f  M . C o l o r then
                       TextOut      ( 1 9 ,I n d e x,'      c o l o r, ')
                    e l s e
                       TextOut      ( 1 9 ,I n d e x,' No   c o l o r, ' ) ;
                    S t r(M  .Row   : 3 ,S ) ;
                    TextOut     ( 2 8 ,I n d e x,S + '   r o w s' ) ;
                    S t r(M  .C o l : 3 ,S ) ;
                    TextOut     ( 3 6 ,i n d e x,S + '   c o l u m n s') ;
                end   ;


                Var
                    i ,Count      :   I n t e g e r;
                   m    :  TVideoMode        ;


                 b e g i n
                    I n i t V i d e o;
                    I n i t K e y b o a r;d
                    Count    := GetVideoModeCount             ;
                    For    I : = 1  t o  Count     do
                        b e g i n
                       GetVideoModeData            ( I -1 ,M  ) ;
                       DumpMode      ( M , I- 1 ) ;
                       end   ;
                    TextOut     ( 1 ,Count    +1 ,  'P r e s s  any    k e y  t o  e x i t' ) ;
                    U p d a t e S c r e e(nF a l s e) ;
                    G e t K e y E v e n;t
                    DoneKeyboard         ;
                    DoneVideo       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.10          GetVideoModeData

    Synopsis:    Get the specifications for a video mode

Declaration:     function  GetVideoModeData(Index:  Word;var  Data:  TVideoMode)  :  Boolean

    Visibility:   default

Description:     GetVideoModeData returns the characteristics of the Index-th video mode in Data.  Index
                is  zero  based,  and  has  a  maximum  value  of  GetVideoModeCount-1.  If  the  current  driver
                does not support setting of modes (GetVideoModeCount=1) and Index is zero, the current
                mode is returned.

                The function returns True if the mode data was retrieved succesfully, False otherwise.

                For an example, see GetVideoModeCount (1621   ).

       Errors:   In case Index has a wrong value, False is returned.

    See also:    GetVideoModeCount (1621   ), SetVideoMode (1625   ), GetVideoMode (1621   )


                                                                                1622

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                35.5.11          InitVideo

    Synopsis:    Initialize video driver.

Declaration:     procedure  InitVideo

    Visibility:   default

Description:     InitVideo Initializes the video subsystem.  If the video system was already initialized,  it
                does nothing.  After the driver has been initialized, the VideoBuf and OldVideoBuf pointers
                are initialized, based on the ScreenWidth and ScreenHeight variables.  When this is done,
                the screen is cleared.

                For an example, see most other functions.

       Errors:   if the driver fails to initialize, the ErrorCode variable is set.

    See also:    DoneVideo (1617   )
                35.5.12          LockScreenUpdate

    Synopsis:    Prevent further screen updates.

Declaration:     procedure  LockScreenUpdate

    Visibility:   default

Description:     LockScreenUpdate increments the screen update lock count with one.  As long as the screen
                update lock count is not zero, UpdateScreen (1626   ) will not actually update the screen.

                This function can be used to optimize screen updating:  If a lot of writing on the screen needs
                to be done (by possibly unknown functions), calling LockScreenUpdate before the drawing,
                and UnlockScreenUpdate (1626   ) after the drawing, followed by a UpdateScreen (1626   ) call,
                all writing will be shown on screen at once.

                For an example, see GetLockScreenCount (1619   ).

       Errors:   None.

    See also:    UpdateScreen (1626   ), UnlockScreenUpdate (1626   ), GetLockScreenCount (1619   )
                35.5.13          SetCursorPos

    Synopsis:    Set write cursor position.

Declaration:     procedure  SetCursorPos(NewCursorX:  Word;NewCursorY:  Word)

    Visibility:   default

Description:     SetCursorPos  positions  the  cursor  on  the  given  position:  Column  NewCursorX  and  row
                NewCursorY. The origin of the screen is the upper left corner, and has coordinates (0,0).

                The current position is stored in the CursorX and CursorY variables.

       Errors:   None.

    See also:    SetCursorType (1624   )


                Listing:  ./videoex/ex2.pp



                                                                                1623

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2;


                 u s e s v i d e o, k e y b o a r d;


                Var
                    P ,PP  ,D   :   I n t e g e r;
                    K :  TKeyEvent       ;


                    P r o c e d u r eP u t S q u a r e (P   :   I N t e g e r; C   :  Char   ) ;


                    b e g i n
                        V i d e o B u f^ [P] : =Ord  ( C )+(  $07    s h l  8 ) ;
                        V i d e o B u f^ [P+S c r e e n W i d t h] : =Ord ( c)+(   $07    s h l  8 ) ;
                        V i d e o B u f^ [P+1]:=   Ord   (c )+(  $07    s h l  8 ) ;
                        V i d e o B u f^ [P+S c r e e n W i d t+h1]:=   Ord   (c )+(  $07    s h l  8 ) ;
                    end  ;


                 b e g i n
                    I n i t V i d e o;
                    I n i t K e y B o a r;d
                    P : = 0 ;
                    PP := -1;
                    Repeat
                        I f PP  <>-1     then
                           P u t S q u a r e(PP , '  ' ) ;
                        P u t S q u a r(eP , '# ' ) ;
                        S e t C u r s o r P o(sP Mod     S c r e e n W i d t,hP  d i v  S c r e e n W i d t)h;
                        U p d a t e S c r e e(nF a l s e) ;
                       PP  := P ;
                       Repeat
                           D : = 0 ;
                           K := T r a n s l a t e K e y E v e n(tG e t K e y E v e n)t;
                           Case     G e t K e y E v e n t C o d(eK)  o f
                               k b d L e f t :  I f  ( P  Mod    S c r e e n W i d t)h<>0    then
                                                 D := -1;
                              kbdUp      :   I f P >=  S c r e e n W i d t hthen
                                              D :=-  S c r e e n W i d t;h
                               k b d R i g h t:   I f  ( (P +2)    Mod    S c r e e n W i d t)h<>0    then
                                                 D : = 1 ;
                              kbdDown        :  i f  ( P<(  V i d e o B u f S i z ed i v 2 ) - ( S c r e e n W i d t*h2 ) )  then
                                                 D :=  S c r e e n W i d t;h
                           end  ;
                        U n t i l (D <>0)     o r  ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
                       P := P + D ;
                    u n t i l G e t K e y E v e n t C h a(rK)=  'q ' ;
                    DoneKeyBoard         ;
                    DoneVideo       ;
                end___.____________________________________________________________________________________________________________*
 *___________

                35.5.14          SetCursorType

    Synopsis:    Set cursor type

Declaration:     procedure  SetCursorType(NewType:  Word)

    Visibility:   default
                                                                                1624

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
Description:     SetCursorType sets the cursor to the type specified in NewType.

                crHidden      Hide cursor

                crUnderLine        Underline cursor

                crBlock     Block cursor

                crHalfBlock       Half block cursor

       Errors:   None.

    See also:    SetCursorPos (1623   )
                35.5.15          SetVideoDriver

    Synopsis:    Install a new video driver.

Declaration:     function  SetVideoDriver(const  Driver:  TVideoDriver)  :  Boolean

    Visibility:   default

Description:     SetVideoDriver  sets  the  videodriver  to  be  used  to  Driver.  If  the  current  videodriver  is
                initialized (after a call to InitVideo) then it does nothing and returns False.

                A new driver can only be installed if the previous driver was not yet activated (i.e.  before a
                call to InitVideo (1623   )) or after it was deactivated (i.e after a call to DoneVideo).

                For more information about installing a videodriver, see viddriver (1607   ).

                For an example, see the section on writing a custom video driver.

       Errors:   If the current driver is initialized, then False is returned.

    See also:    viddriver (1607   )
                35.5.16          SetVideoMode

    Synopsis:    Set current video mode.

Declaration:     function  SetVideoMode(const  Mode:  TVideoMode)  :  Boolean

    Visibility:   default

Description:     SetVideoMode sets the video mode to the mode specified in Mode:

                If the call was succesful, then the screen will have Col columns and Row rows, and will be
                displaying in color if  Color is True.

                The function returns True if the mode was set succesfully, False otherwise.

                Note that the video mode may not always be set.  E.g.  a console on Linux or a telnet session
                cannot always set the mode.  It is important to check the error value returned by this function
                if it was not succesful.

                The mode can be set when the video driver has not yet been initialized (i.e.  before InitVideo
                (1623   )  was  called)  In  that  case,  the  video  mode  will  be  stored,  and  after  the  driver  was
                initialized, an attempt will be made to set the requested mode.  Changing the video driver
                before the call to InitVideo will clear the stored video mode.

                To know which modes are valid,  use the GetVideoModeCount (1621   ) and GetVideoMode-
                Data (1622   ) functions.  To retrieve the current video mode, use the GetVideoMode (1621   )
                procedure.

       Errors:   If the specified mode cannot be set, then errVioNoSuchMode may be set in ErrorCode

    See also:    GetVideoModeCount (1621   ), GetVideoModeData (1622   ), GetVideoMode (1621   )



                                                                                1625

                ____________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________
                35.5.17          UnlockScreenUpdate

    Synopsis:    Unlock screen update.

Declaration:     procedure  UnlockScreenUpdate

    Visibility:   default

Description:     UnlockScreenUpdate decrements the screen update lock count with one if it is larger than
                zero.  When the lock count reaches zero, the UpdateScreen (1626   ) will actually update the
                screen.   No  screen  update  will  be  performed  as  long  as  the  screen  update  lock  count  is
                nonzero.  This mechanism can be used to increase screen performance in case a lot of writing
                is done.

                It is important to make sure that each call to LockScreenUpdate (1623   ) is matched by exactly
                one call to UnlockScreenUpdate

                For an example, see GetLockScreenCount (1619   ).

       Errors:   None.

    See also:    LockScreenUpdate (1623   ), GetLockScreenCount (1619   ), UpdateScreen (1626   )
                35.5.18          UpdateScreen

    Synopsis:    Update physical screen with internal screen image.

Declaration:     procedure  UpdateScreen(Force:  Boolean)

    Visibility:   default

Description:     UpdateScreen  synchronizes  the  actual  screen  with  the  contents  of  the  VideoBuf  inter-
                nal  buffer.   The  parameter  Force  specifies  whether  the  whole  screen  has  to  be  redrawn
                (Force=True) or only parts that have changed since the last update of the screen.

                The Video unit keeps an internal copy of the screen as it last wrote it to the screen (in the
                OldVideoBuf array).  The current contents of  VideoBuf are examined to see what locations
                on  the  screen  need  to  be  updated.   On  slow  terminals  (e.g.   a  linux  telnet  session)  this
                mechanism can speed up the screen redraw considerably.

                On platforms where mouse cursor visibility is not guaranteed to be preserved during screen
                updates  this  routine  has  to  restore  the  mouse  cursor  after  the  update  (usually  by  calling
                HideMouse from unit Mouse before the real update and ShowMouse afterwards).

                For an example, see most other functions.

       Errors:   None.

    See also:    ClearScreen (1616   )



                                                                                1626


                Chapter   36


                Reference   for   unit   'wincrt'
                36.1          Overview


                The wincrt unit provides some auxiliary routines for use with the graph (574  ) unit, namely
                keyboard support.  It has no connection with the crt (381  ) unit, nor with the Turbo-Pascal
                for  Windows  WinCrt  unit.  As  such,  it  should  not  be  used  by  end  users.  Refer  to  the  crt
                (381  ) unit instead.
                36.2          Constants,  types  and  variables



                36.2.1         Variables

                directvideo  :  Boolean


                On windows, this variable is ignored.


                lastmode  :  Word


                Is supposed to contain the last used video mode, but is actually unused.
                36.3          Procedures  and  functions



                36.3.1         delay

    Synopsis:    Pause program execution

Declaration:     procedure  delay(ms:  Word)

    Visibility:   default

Description:     Delay stops program execution for the indicated number ms of milliseconds.

    See also:    sound (1628   ), nosound (1628   )
                36.3.2         keypressed

    Synopsis:    Check if a key was pressed.



                                                                            1627

                _________________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'WINCRT'_________________*
 *___________________
Declaration:     function  keypressed  :  Boolean

    Visibility:  default

Description:     KeyPressed returns True if the user pressed a key, or False if not.  It does not wait for the
                user to press a key.

    See also:    readkey (1628   )
                36.3.3         nosound

    Synopsis:    Stop the speaker

Declaration:     procedure  nosound

    Visibility:   default

Description:     NoSound does nothing, windows does not support this.

    See also:    sound (1628   )
                36.3.4         readkey

    Synopsis:    Read a key from the keyboard

Declaration:     function  readkey  :  Char

    Visibility:   default

Description:     ReadKey  reads  a  key  from  the  keyboard,  and  returns  the  ASCII  value  of  the  key,  or  the
                scancode of the key in case it is a special key.

                The function waits until a key is pressed.

    See also:    KeyPressed (1627   )
                36.3.5         sound

    Synopsis:    Sound PC speaker

Declaration:     procedure  sound(hz:  Word)

    Visibility:   default

Description:     Sound sounds the PC speaker.  It emits a tone with frequency Hz for 500 milliseconds.  (the
                time argument is required by the windows API)

    See also:    nosound (1628   )
                36.3.6         textmode

    Synopsis:    Set indicated text mode

Declaration:     procedure  textmode(mode:  Integer)

    Visibility:   default

Description:     TextMode does nothing.

                                                                                1628


                Chapter   37


                Reference   for   unit   'x86'
                37.1          Used  units
                                                      Table 37.1:  Used units by unit 'x86'


                                                                  _Name_____________Page______
                                                                    BaseUnix            94



                37.2          Overview


                The x86 unit contains some of the routines that were present in the 1.0.X Linux unit, and
                which were Intel (PC) architecture specific.

                These calls have been preserved for compatibility, but should be considered deprecated:  they
                are not portable and may not even work on future linux versions.
                37.3          Procedures  and  functions



                37.3.1         fpIOperm

    Synopsis:    Set permission on IO ports

Declaration:     function  fpIOperm(From:  Cardinal;Num:  Cardinal;Value:  cint)  :  cint

    Visibility:   default

Description:     FpIOperm  sets  permissions  on  Num  ports  starting  with  port  From  to  Value.  The  function
                returns zero if the call was successfull, a nonzero value otherwise.

                Note:

                      oThis works ONLY as root.

                      oOnly the first 0x03ff ports can be set.

                      oWhen doing a FpFork (142  ), the permissions are reset.  When doing a FpExecVE (139  )
                       they are kept.

       Errors:   Extended error information can be retrieved with FpGetErrno (145  )



                                                                            1629

                _________________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________
                37.3.2         fpIoPL

    Synopsis:    Set I/O privilege level

Declaration:     function  fpIoPL(Level:  cint)  :  cint

    Visibility:   default

Description:     FpIoPL sets the I/O privilige level.  It is intended for completeness only, one should normally
                not use it.
                37.3.3         ReadPort

    Synopsis:    Read data from a PC port

Declaration:     procedure  ReadPort(Port:  LongInt;var  Value:  Byte)
                procedure  ReadPort(Port:  LongInt;var  Value:  LongInt)
                procedure  ReadPort(Port:  LongInt;var  Value:  Word)

    Visibility:   default

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 FpIOPerm (1629   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1629   ),  ReadPortB  (1630   ),  ReadPortW  (1631   ),  ReadPortL  (1631   ),  WritePort
                (1631   ), WritePortB (1632   ), WritePortL (1632   ), WritePortW (1632   )
                37.3.4         ReadPortB

    Synopsis:    Read bytes from a PC port

Declaration:     function  ReadPortB(Port:  LongInt)  :  Byte
                procedure  ReadPortB(Port:  LongInt;var  Buf;Count:  LongInt)

    Visibility:   default

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 FpIOPerm (1629   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1629   ),  ReadPort  (1630   ),  ReadPortW  (1631   ),  ReadPortL  (1631   ),  WritePort
                (1631   ), WritePortB (1632   ), WritePortL (1632   ), WritePortW (1632   )
                                                                                1630

                _________________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________
                37.3.5         ReadPortL

    Synopsis:    Read longints from a PC port

Declaration:     function  ReadPortL(Port:  LongInt)  :  LongInt
                procedure  ReadPortL(Port:  LongInt;var  Buf;Count:  LongInt)

    Visibility:   default

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  ReadPortL 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 FpIOPerm (1629   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1629   ),  ReadPort  (1630   ),  ReadPortW  (1631   ),  ReadPortB  (1630   ),  WritePort
                (1631   ), WritePortB (1632   ), WritePortL (1632   ), WritePortW (1632   )
                37.3.6         ReadPortW

    Synopsis:    Read Words from a PC port

Declaration:     function  ReadPortW(Port:  LongInt)  :  Word
                procedure  ReadPortW(Port:  LongInt;var  Buf;Count:  LongInt)

    Visibility:   default

Description:     The procedural form of  ReadPortW 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  ReadPortW 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 FpIOPerm (1629   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm (1629   ), ReadPort (1630   ), ReadPortB (1630   ), ReadPortL (1631   ), WritePort (1631   ),
                WritePortB (1632   ), WritePortL (1632   ), WritePortW (1632   )
                37.3.7         WritePort

    Synopsis:    Write data to PC port

Declaration:     procedure  WritePort(Port:  LongInt;Value:  Byte)
                procedure  WritePort(Port:  LongInt;Value:  LongInt)
                procedure  WritePort(Port:  LongInt;Value:  Word)

    Visibility:   default

Description:     WritePort writes Value - 1 byte, Word or longint - to port Port.

 Remark:         You need permission to write to a port.  This permission can be set with root permission
                with the FpIOPerm (1629   ) call.



                                                                                1631

                _________________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________
       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1629   ), WritePortB (1632   ), WritePortL (1632   ), WritePortW (1632   ), ReadPortB
                (1630   ), ReadPortL (1631   ), ReadPortW (1631   )
                37.3.8         WritePortB

    Synopsis:    Write byte to PC port

Declaration:     procedure  WritePortB(Port:  LongInt;Value:  Byte)
                procedure  WritePortB(Port:  LongInt;var  Buf;Count:  LongInt)

    Visibility:   default

Description:     The first form of  WritePortB writes 1 byte to port Port.  The second form writes Count
                bytes from Buf to port Port.

 Remark:         You need permission to write to a port.  This permission can be set with root permission
                with the FpIOPerm (1629   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1629   ),  WritePort (1631   ),  WritePortL (1632   ),  WritePortW (1632   ),  ReadPortB
                (1630   ), ReadPortL (1631   ), ReadPortW (1631   )
                37.3.9         WritePortl

    Synopsis:    Write longint to PC port.

Declaration:     procedure  WritePortL(Port:  LongInt;Value:  LongInt)
                procedure  WritePortl(Port:  LongInt;var  Buf;Count:  LongInt)

    Visibility:   default

Description:     The first form of  WritePortB writes 1 byte to port Port.  The second form writes Count
                bytes from Buf to port Port.

 Remark:         You need permission to write to a port.  This permission can be set with root permission
                with the FpIOPerm (1629   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1629   ), WritePort (1631   ), WritePortB (1632   ), WritePortW (1632   ), ReadPortB
                (1630   ), ReadPortL (1631   ), ReadPortW (1631   )
                37.3.10          WritePortW

    Synopsis:    Write Word to PC port

Declaration:     procedure  WritePortW(Port:  LongInt;Value:  Word)
                procedure  WritePortW(Port:  LongInt;var  Buf;Count:  LongInt)

    Visibility:   default



                                                                                1632

                _________________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________
Description:     The first form of  WritePortB writes 1 byte to port Port.  The second form writes Count
                bytes from Buf to port Port.

 Remark:         You need permission to write to a port.  This permission can be set with root permission
                with the FpIOPerm (1629   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm  (1629   ),  WritePort  (1631   ),  WritePortL  (1632   ),  WritePortB  (1632   ),  ReadPortB
                (1630   ), ReadPortL (1631   ), ReadPortW (1631   )
                                                                                1633
